Does an approval event mean that the action executed?

An approved event records the human decision. The complete audit event and tool records establish whether execution started, which effects occurred, and what outcome followed.

Why does the schema use approved and rejected while the API uses APPROVE and REJECT?

The API route accepts operational decision commands and the public schema records the normalized event vocabulary. The implementation mapping makes that boundary explicit.

Can the requester approve their own action?

The current approval routes apply maker-checker separation and reject self-approval for pending requests. The schema records the resulting reviewer and decision; it does not evaluate identity authority.

Technical reference · v1.0.0

AI Agent Approval Event Schema

An approval event records the decision lifecycle for a governed AI agent action that reached human review. This standalone reference preserves the approval definition from the published audit event and adds an addressable approval_event_id plus correlation for independent use.

Download JSON Schema Download approved example

JSON Schema draft 2020-12 · Version 1.0.0 · Maker-checker decision record

Definition: A standalone record of an approval request’s status, required role, human reviewer when decided, decision, timing, and optional rationale references.
When used: Create it after a policy result routes an action to human approval and record it when the request is decided, expires, or is cancelled.
Decision values: approved, rejected, expired, and cancelled describe the terminal decision represented by the event.
Maker-checker: The current approval routes check approval:decide, required role, pending state, and separation of duties before a decision is recorded.

Schema and approval examples

The versioned schema and two terminal decision examples are self-contained artifacts for validation and reference implementation.

JSON SchemaDraft 2020-12 JSON Schema, version 1.0.0./ai-agent-approval-event/v1/schema.jsonDownload Approved event exampleDecided approval with a synthetic human reviewer./ai-agent-approval-event/v1/examples/approved.jsonDownload Rejected event exampleDecided rejection with a reason code and rationale reference./ai-agent-approval-event/v1/examples/rejected.jsonDownload

Object and execution order

An approval event sits between a require_approval policy result and any approved tool effect. Expired and rejected paths remain linkable denied or unstarted outcomes.

01RequestA policy result of require_approval creates a request associated with the execution correlation and a required role.
02ReviewA reviewer receives the presented evidence and acts through an approval route with approval:decide permission.
03CheckThe current routes check the required role, pending status, and maker-checker separation. Approval also requires an explicit acknowledgement.
04RecordThe decision is persisted and a durable audit obligation is written before the gated workflow is signalled to resume.

Field dictionary

The dictionary covers every approval member, including lifecycle conditionals and optional reassignment, override, and appeal references.

Standalone identity and correlation

Field	Status	Purpose
schema_version	Required	Selects the compatibility contract used to parse the record.
approval_event_id	Required	Independently addresses this approval event and links it to an audit event. Added for standalone publication.
correlation.correlation_id / execution_id	Required	Joins the approval to the request, policy, tool, and audit sequence. Added for standalone publication.
correlation.trace_id / span_id / parent_event_id	Optional	Carries OpenTelemetry trace context and an optional parent event. All-zero W3C identifiers are invalid.

Approval request lifecycle

Field	Status	Purpose
request_id	Required	Identifies the approval request being decided. This keeps the embedded approval.request_id meaning.
status	Required	States whether the event is decided, expired, or cancelled.
requested_at / expires_at	Required	Records the request and expiry times as RFC 3339 date-times.
required_role	Required	Names the role required to decide the approval.
decided_at	Required	Records when the terminal decision, expiry, or cancellation was recorded.

Decision and supporting references

Field	Status	Purpose
decision	Required	Carries approved, rejected, expired, or cancelled and matches the lifecycle status.
reviewer	Conditional	Identifies the human reviewer when status is decided. The type is always user.
presented_evidence_digest	Optional	Binds the decision to the evidence representation shown for review.
reason_code / rationale_reference	Optional	Provides a stable reason and reference to a fuller decision rationale.
reassigned_from	Optional	Preserves the prior principal when an approval request changes assignee.
override.authority_reference / reason_code	Optional	References exceptional authority and its reason when an override is recorded.
appeal.status / reference	Optional	Links a later appeal lifecycle and its stable reference.

Minimal example

The approved record shows the required fields plus the reviewer needed for a decided status. The rejected record provides a second terminal decision.

{
  "schema_version": "1.0.0",
  "approval_event_id": "evt_approval_demo_0001",
  "correlation": {
    "correlation_id": "corr_credit_review_demo_0002",
    "execution_id": "exec_credit_review_demo_0002"
  },
  "request_id": "approval_req_demo_0001",
  "status": "decided",
  "requested_at": "2026-07-21T11:03:18.240Z",
  "expires_at": "2026-07-21T11:33:18.240Z",
  "required_role": "kla:senior_approver",
  "presented_evidence_digest": "sha256:9999999999999999999999999999999999999999999999999999999999999999",
  "reviewer": {
    "id": "user_reviewer_demo_0001",
    "type": "user",
    "display_name": "Synthetic reviewer",
    "identity_provider": "demo-idp"
  },
  "decision": "approved",
  "reason_code": "evidence_reviewed",
  "rationale_reference": "rationale_demo_0001",
  "decided_at": "2026-07-21T11:04:10.240Z"
}

Validation and digest verification

JSON Schema validation checks status and decision shape. The companion verifier reproduces a sha256: digest over the canonical record and can check an optional detached Ed25519 signature.

01Load the versioned schema from the JSON Schema download URL.
02Validate the JSON document with a draft 2020-12 validator and a date-time format plugin.
03Canonicalize the complete standalone record with recursively sorted object keys, matching the published audit-event verifier approach.
04Compute SHA-256 over the canonical bytes and represent the result with the sha256: prefix.
05Compare the computed digest with the digest retained by the calling evidence procedure.
06When a detached Ed25519 signature is supplied, resolve its public key independently and verify the signature over the 32-byte digest.
07Record a hash mismatch or signature failure as a failed verification result. Preserve the decision record and its linked request for review.

Terminal decision examples

The approved and rejected examples validate against draft 2020-12 and produce reproducible sha256: digests from their canonical content.

Tamper check

Changing the decision changes both the lifecycle meaning and the canonical digest. The verifier reportsrecord_hash_mismatch.

The standalone verifier accepts an optional detached Ed25519 signature. Trust in a public key comes from the caller’s independently governed key registry.

Compatibility and versioning

Version the approval event contract independently from the approval service and policy contract.

Patch

Clarifications, descriptions, and examples can change while validation behavior remains stable. A corrected immutable artifact receives a new versioned URL.

Minor

New optional fields require a new schema_version and versioned URL. Consumers declare support before processing the new version.

Major

Removed or renamed fields, changed meanings, stricter required status, or changed canonicalization require a new major path.

Consumers preserve unknown versions for review and stop semantic processing until support is declared. The v1 path uses schema_version 1.0.0.

How KLA implements this

The worker creates approval audit records. The API routes enforce decision authority and persist a durable decision obligation.

Approval event fields mapped to current KLA implementation sources
Contract area	Current source	Mapping	Status
Approval request and resolution events	services/execution-worker/src/services/audit-events.ts	The worker records approval requested and resolved audit events with execution, approval, governance, decision, reason, and trace-related fields. This page normalizes those facts to the portable approval event shape.	Current producer with normalization
Maker-checker decision route	services/execution-api/src/routes/approvals.ts	The route checks approval:decide permission, required role, pending state, and self-approval. Approve also requires explicit acknowledgement; an escalation keeps the request pending.	Current consumer and producer
Decision Desk and local approval route	services/api/src/routers/approvals.ts	The router applies the same permission and maker-checker access rules, validates policy and evidence check sets, persists a decision record, and coordinates local or execution-api approval state.	Current consumer and producer
Decision vocabulary and version	services/shared/src/policy/contracts.ts	The shared policy contract supplies require_approval as the route that leads to this event and keeps policy versioning independent from the approval event schema.	Current shared contract

Deliberate abstractions and unsupported fields

•The schema omits tenant database IDs, approval table columns, Cerbos authorization syntax, and raw request or evidence contents.
•The schema records required_role and reviewer identity. It does not prove that the reviewer held that role at the decision time; consumers perform that authority check.
•The schema has terminal status values decided, expired, and cancelled. The current API’s escalation action keeps the request pending and has no terminal escalated value in this contract.
•The schema carries optional evidence, rationale, reassignment, override, and appeal references. It does not define the evidence bundle, appeal procedure, or override authority policy.
•The schema does not publish reviewer email, role snapshots, comments, or decision receipts. Those fields remain in the KLA decision and audit records and can be linked by the correlation and request IDs.
•The standalone approval_event_id and correlation object are additions for standalone publication. request_id retains the approval request meaning from the embedded approval object.

Related references

Follow the execution sequence from action request to policy decision, approval when required, and the complete audit event.

Action request schema

The action that reached policy evaluation.

Policy decision schema

The require_approval result that routes the action to review.

Audit log schema

The full event envelope that records the request, decision, approval, effect, and outcome.

Apply the contract

Keep the human decision linked to the policy branch it resolves.

Use the correlation and request identifiers to connect the approval event to the action request, policy decision, complete audit event, and later evidence records.

AI agent policy decision schema AI agent audit log schema