# description
Canonical machine-verifiable structure of an OpenAuditModel audit event. Version 0.1 is experimental. Core objects reject unknown properties: domain-specific data belongs in `metadata`, `extensions`, `attributes`, or in an OpenAuditModel profile.

# $comment
Normative reference: specification/event-model.md. Patterns in this schema deliberately avoid look-around and back-references so that they remain portable across ECMA-262, RE2 and PCRE regular expression engines.

# properties.specVersion.$comment
Constant in v0.1. The compatibility strategy for later versions is defined in specification/overview.md.

# properties.specVersion.description
OpenAuditModel specification version this event conforms to.

# properties.id.description
Globally unique, idempotent identifier of this audit event. No identifier technology is mandated; UUIDv4, UUIDv7 or ULID are RECOMMENDED. Receivers MAY use this value to deduplicate redelivered events.

# properties.time.description
When the audited operation occurred, as observed by the producing application. UTC is RECOMMENDED.

# properties.observedTime.description
When a collector, exporter, gateway or receiving system observed this event. MUST NOT be assumed equal to `time`.

# properties.sequence.description
Producer-assigned monotonically increasing ordinal used to order events that share a timestamp. Ordering is only meaningful within a single producer, partition or integrity chain.

# properties.actor.description
Principal that technically performed the operation.

# properties.subject.description
Principal on whose behalf the actor performed the operation. This is NOT the audited target; the audited target is `resource`.

# properties.resource.description
Primary resource the audited operation acted upon.

# properties.relatedResources.description
Additional resources affected by, or required to interpret, the same operation.

# properties.evidence.description
References to material supporting this event. Evidence is referenced, never embedded.

# properties.controlCategories.description
Regulation-neutral control categories this event contributes evidence to. Regulation, framework and jurisdiction identifiers MUST NOT appear here; they belong to external mapping artifacts.

# properties.tags.description
Producer-defined labels for filtering and routing. Tags carry no normative meaning.

# properties.metadata.description
Domain-specific audit interpretation data that has no core representation. Values SHOULD be small and structured. MUST NOT contain secrets, large payloads or duplicate copies of core fields.

# properties.extensions.description
Vendor-specific or domain-specific additions. Every key MUST be a reverse-domain namespaced name of at least three dot-separated segments. Extensions MUST NOT weaken required core fields or redefine the meaning of core fields.

# allOf[].$comment
Delegation types that act for another principal require that principal to be identified. `service-chain` describes transport-level chaining and does not by itself imply a subject.

# $defs.jsonValue.description
Any JSON value: string, number, integer, boolean, null, array or object.

# $defs.jsonObject.description
A JSON object whose values may be any JSON value.

# $defs.identifier.description
Opaque, stable identifier. Leading and trailing whitespace are not permitted and the value MUST NOT be empty.

# $defs.token.description
Lower-case, hyphen-separated vocabulary term. Used for open vocabularies whose recommended values are listed in the semantic conventions.

# $defs.eventName.description
Hierarchical lower-case event name in the form domain.resource.action. At least two segments are REQUIRED. Segments may contain hyphenated words such as `offset-reset`. Event names MUST NOT contain product, company or jurisdiction names.

# $defs.extensionKey.description
Reverse-domain namespaced extension key with at least three dot-separated lower-case segments, for example `com.example.workflow.stage`.

# $defs.timestamp.description
RFC 3339 compatible date-time string. UTC is RECOMMENDED.

# $defs.text.description
Short human readable text. MUST NOT contain secrets, credentials, tokens or unnecessary personal data.

# $defs.algorithmIdentifier.description
Cryptographic algorithm identifier. The vocabulary is intentionally open so that new algorithms may be adopted without a specification change.

# $defs.digest.description
Encoded hash or signature value produced by another system or layer, such as an evidence digest or a signature. Hexadecimal, base64 and base64url encodings are accepted, because the value is often echoed from the system that produced it. Digests that OpenAuditModel itself verifies use `hexDigest` instead.

# $defs.hexDigest.description
Digest that OpenAuditModel tooling recalculates and compares, encoded as lower-case hexadecimal with an even number of digits. A single encoding is mandated because a digest that could be hexadecimal or base64 cannot be compared without guessing. See specification/integrity.md §5.

# $defs.traceId.description
W3C Trace Context trace-id: 32 lower-case hexadecimal characters. The all-zero value is invalid.

# $defs.spanId.description
W3C Trace Context parent-id: 16 lower-case hexadecimal characters. The all-zero value is invalid.

# $defs.eventDescriptor.properties.category.description
Coarse grouping of the event name. Open vocabulary; recommended values are listed in semantic-conventions/event-naming.md.

# $defs.eventDescriptor.properties.type.description
Optional activity classifier that is independent of the domain, such as the coarse operation performed.

# $defs.eventDescriptor.properties.outcome.description
Result of the audited operation. `partial` describes an operation that succeeded for some targets and failed for others.

# $defs.eventDescriptor.properties.severity.description
Audit significance of the event, not the severity of a software fault.

# $defs.eventDescriptor.properties.summary.description
Short human readable description. Machine consumers MUST NOT parse this field.

# $defs.eventDescriptor.allOf[].$comment
A failed operation carries a sanitized error descriptor so that failures remain analyzable without free-text parsing.

# $defs.errorDescriptor.description
Sanitized description of why an operation failed. MUST NOT contain secrets, tokens, credentials, personal data, full payloads, or internal stack traces unless explicitly permitted by policy.

# $defs.errorDescriptor.properties.code.description
Stable, machine-readable failure code defined by the producing application.

# $defs.errorDescriptor.properties.message.description
Sanitized human readable failure message.

# $defs.errorDescriptor.properties.retryable.description
Whether the same operation may reasonably succeed if retried.

# $defs.principal.description
An actor or a subject. Stable identifiers are sufficient; personally identifiable display names are never required.

# $defs.principal.properties.type.description
Kind of principal. A principal that does not fit a core type SHOULD use the closest core type and describe the detail in `attributes`.

# $defs.principal.properties.id.description
Stable identifier of the principal within its issuing authority. SHOULD NOT be an email address or another direct personal identifier when a stable opaque identifier exists.

# $defs.principal.properties.displayName.description
OPTIONAL human readable name. Personal data; include only when required by the audit purpose.

# $defs.principal.properties.tenantId.description
Tenant the principal belongs to, when the application is multi-tenant.

# $defs.principal.properties.roles.description
Roles held by the principal that are relevant to this operation. This is not a complete role inventory.

# $defs.principal.properties.attributes.description
Additional producer-defined principal attributes. MUST NOT contain credentials or unnecessary personal data.

# $defs.delegation.description
How authority to perform the operation was transferred from the subject to the actor.

# $defs.delegation.properties.type.description
`impersonation`: the actor assumed the subject's identity. `on-behalf-of`: the actor acted for the subject with its own identity. `delegated`: authority was granted in advance. `service-chain`: the operation traversed intermediate services.

# $defs.delegation.properties.reference.description
Identifier of the grant, ticket or session that authorized the delegation.

# $defs.delegation.properties.approvedBy.description
Principal that approved the delegation, when delegation required approval.

# $defs.resourceReference.description
A resource the operation acted upon. Resource types are an open vocabulary and MUST NOT be enumerated in the core schema.

# $defs.resourceReference.properties.id.description
Stable identifier of the resource within the producing application.

# $defs.resourceReference.properties.name.description
OPTIONAL human readable resource name. May itself be sensitive.

# $defs.resourceReference.properties.parentId.description
Identifier of the containing resource, such as a folder, project or cluster.

# $defs.resourceReference.properties.classification.description
Data classification of the resource. Open vocabulary because classification schemes are organization-defined. Recommended values: public, internal, confidential, restricted, secret, unknown.

# $defs.resourceReference.properties.ownerId.description
Identifier of the owning principal or team.

# $defs.resourceReference.properties.attributes.description
Additional producer-defined resource attributes. MUST NOT contain resource contents.

# $defs.application.description
The application that produced the event. This MUST describe the producer, not a collector, forwarder or storage backend.

# $defs.application.properties.name.description
Stable name of the producing application. Lower-case hyphenated names are RECOMMENDED.

# $defs.application.properties.environment.description
Deployment environment. Open vocabulary. Recommended values: local, development, test, staging, production, disaster-recovery, unknown.

# $defs.application.properties.instance.description
Identifier of the specific running instance, such as a pod, host or process.

# $defs.application.properties.service.description
Service within the application that produced the event.

# $defs.application.properties.region.description
Deployment region identifier as defined by the operator.

# $defs.application.properties.zone.description
Deployment zone identifier as defined by the operator.

# $defs.application.properties.deploymentId.description
Identifier of the deployment or release the instance is running.

# $defs.organization.description
OPTIONAL organizational placement of the operation. Not every application is multi-tenant, so this object is never required.

# $defs.authentication.description
How the actor was authenticated. Absence of this object means authentication context is not available or not applicable; it does NOT mean the actor was anonymous.

# $defs.authentication.properties.provider.description
Identity provider that performed authentication.

# $defs.authentication.properties.mfa.description
Whether multi-factor authentication was satisfied for the session behind this operation.

# $defs.authentication.properties.assuranceLevel.description
Producer-defined authentication assurance level. Values are application-defined; mapping to an external assurance framework is out of scope for the core specification.

# $defs.authentication.properties.sessionId.description
Session correlation identifier. MUST NOT be a usable session token or cookie value.

# $defs.authentication.properties.authenticatedAt.description
When the session behind this operation was authenticated.

# $defs.authorization.description
The authorization decision that permitted or denied the operation. OpenAuditModel records decisions; it is not an authorization engine.

# $defs.authorization.properties.decision.description
Outcome of the authorization evaluation.

# $defs.authorization.properties.engine.description
Component that produced the decision. No specific engine is required or implied.

# $defs.authorization.properties.policy.description
Identifier of the policy that produced the decision.

# $defs.authorization.properties.policyVersion.description
Version of the policy that produced the decision.

# $defs.authorization.properties.permissions.description
Permissions that were evaluated or required for the operation.

# $defs.approval.description
Human or workflow approval associated with the operation. Approval is distinct from authorization: authorization is a policy evaluation, approval is a decision by one or more principals.

# $defs.approval.properties.status.description
State of the approval at the time of the event.

# $defs.approval.properties.workflowId.description
Identifier of the approval workflow definition or instance.

# $defs.approval.properties.receivedApprovals.description
Number of approvals received at the time of the event.

# $defs.approval.properties.approvedAt.description
When the approval reached its current status.

# $defs.request.description
How the operation was requested and how it correlates with other telemetry.

# $defs.request.properties.requestId.description
Identifier of the request that triggered the operation.

# $defs.request.properties.correlationId.description
Identifier correlating a set of related requests or operations.

# $defs.request.properties.ipAddress.description
Network address the request originated from. Personal data in most jurisdictions; record only when the audit purpose requires it.

# $defs.request.properties.forwardedFor.description
Ordered list of proxy-reported client addresses. Structured deliberately so that raw forwarding headers are not copied verbatim.

# $defs.request.properties.userAgent.description
Client user agent string, truncated by the producer when necessary.

# $defs.request.properties.protocol.description
Application protocol used for the request. Open vocabulary.

# $defs.request.properties.method.description
Protocol-level operation, such as an HTTP method or an RPC verb.

# $defs.request.properties.route.description
Route template rather than a resolved URL. Query strings and fragments are rejected so that identifiers and search terms are not captured incidentally.

# $defs.change.description
What the operation changed. Complete before and after states are never required: changed fields, sanitized state, hashes or references are all acceptable.

# $defs.change.properties.changedFields.description
Paths of the fields that changed. Field paths alone are often sufficient and avoid recording values.

# $defs.change.properties.before.description
Sanitized prior state or the subset of it that changed. MUST NOT contain full database records, credentials or sensitive payloads.

# $defs.change.properties.after.description
Sanitized resulting state or the subset of it that changed. MUST NOT contain full database records, credentials or sensitive payloads.

# $defs.change.properties.beforeHash.description
Digest of the prior state, for verification without disclosure.

# $defs.change.properties.afterHash.description
Digest of the resulting state, for verification without disclosure.

# $defs.change.properties.ticketId.description
Change or service ticket associated with the change.

# $defs.change.properties.deploymentId.description
Deployment or release associated with the change.

# $defs.reason.description
Why the operation was performed. This is a business justification and MUST NOT be confused with a technical error message.

# $defs.reason.properties.code.description
Machine-readable justification code from a producer-defined vocabulary.

# $defs.reason.properties.reference.description
Identifier or locator of the record that justifies the operation, such as a ticket or case.

# $defs.evidenceItem.description
A reference to supporting material. OpenAuditModel does not define evidence storage. References MUST be access-controlled and MUST NOT embed credentials.

# $defs.evidenceItem.properties.reference.description
Locator or identifier of the evidence in its own system. MUST NOT contain credentials, tokens or signed access parameters.

# $defs.evidenceItem.properties.hash.description
Digest of the referenced evidence, allowing later verification that it was not altered.

# $defs.evidenceItem.properties.retentionUntil.description
When the evidence may be disposed of, according to the owning system.

# $defs.evidenceItem.properties.legalHold.description
Whether the evidence is currently under a hold that suspends disposal.

# $defs.privacy.description
How this event relates to personal data. Regulation-specific fields MUST NOT be added here; regulatory interpretation belongs to external mapping artifacts.

# $defs.privacy.properties.containsPersonalData.description
Whether the event as serialized contains personal data.

# $defs.privacy.properties.dataCategories.description
Categories of personal data present. Open vocabulary; recommended values are listed in specification/privacy.md.

# $defs.privacy.properties.processing.description
How personal data was handled when the event was produced.

# $defs.privacy.properties.minimized.description
Whether the producer applied data minimization to this event.

# $defs.privacy.properties.retentionClass.description
Producer-defined retention class governing this event.

# $defs.privacy.properties.purpose.description
Purpose for which the event is recorded.

# $defs.integrity.description
Tamper-evidence material for this event. Integrity metadata makes alteration detectable; it does not make events immutable, prevent deletion, or replace write-once storage.

# $defs.integrity.properties.canonicalization.description
Canonicalization applied before hashing. `RFC8785`, the JSON Canonicalization Scheme, is the identifier the OpenAuditModel verifier implements. REQUIRED when `hash` is present: a digest whose canonicalization is unknown cannot be recalculated.

# $defs.integrity.properties.hashAlgorithm.description
Algorithm used to produce `hash` and `previousHash`. Open vocabulary, matched case-sensitively; the v0.1 verifier implements SHA-256, SHA-384 and SHA-512. Acceptance by this schema is not a claim of verifier support.

# $defs.integrity.properties.hash.description
Digest of the canonicalized event, calculated over the event with `/integrity/hash` and `/integrity/signature` removed. See specification/integrity.md §4.

# $defs.integrity.properties.previousHash.description
Digest of the preceding event in the same chain, forming a tamper-evident sequence. Every event in one chain MUST use the same `hashAlgorithm` and `canonicalization`.

# $defs.integrity.properties.chainId.description
Identifier of the chain this event belongs to. Chains may be per instance, per partition or per batch; a single global chain is NOT required.

# $defs.integrity.properties.batchId.description
Identifier of the batch this event was sealed with.

# $defs.signature.description
Digital signature over the canonicalized event. A signature does not by itself create legal evidentiary status, and key management is outside the core specification.

# $defs.signature.properties.algorithm.description
Signature algorithm. Open vocabulary; recommended values include Ed25519, ECDSA-P256-SHA256 and RSA-PSS-SHA256.

# $defs.signature.properties.keyId.description
Identifier of the verification key. MUST NOT contain key material.