# KYA-OS Protocol Schemas

> The canonical registry of JSON Schemas for the KYA-OS protocol. Every schema is versioned and served at a stable $id URL with open CORS.

The canonical registry for the KYA-OS protocol's JSON Schemas. Every schema is versioned and immutable, served at a stable $id URL with open CORS. Reference one to validate KYA-OS messages, or to resolve $ref pointers from any JSON Schema validator.

## Schemas

- [KYA-OS Supporting Checkpoint Anchor Receipt v1](https://schema.kya-os.org/v1/protocol/audit/anchor-receipt/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Replay Bundle Component v1](https://schema.kya-os.org/v1/protocol/audit/bundle-component/v1.0.0): One included or explicitly omitted replay-bundle inventory component, matching the @kya-os/mcp v1.11.0 runtime contract.
- [KYA-OS Audit Bundle Consistency Proof v1](https://schema.kya-os.org/v1/protocol/audit/bundle-consistency-proof/v1.0.0): Ledger-bound RFC 9162 consistency proof used as a replay-bundle component.
- [KYA-OS Audit Bundle Inclusion Proof v1](https://schema.kya-os.org/v1/protocol/audit/bundle-inclusion-proof/v1.0.0): Ledger-bound RFC 9162 inclusion proof used as a replay-bundle component.
- [KYA-OS Audit Bundle Manifest Core v1](https://schema.kya-os.org/v1/protocol/audit/bundle-manifest/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Checkpoint Core v1](https://schema.kya-os.org/v1/protocol/audit/checkpoint/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Consistency Proof Request v1](https://schema.kya-os.org/v1/protocol/audit/consistency-proof-request/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS Audit Consistency Proof Response v1](https://schema.kya-os.org/v1/protocol/audit/consistency-proof-response/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS RFC 9162 Consistency Proof v1](https://schema.kya-os.org/v1/protocol/audit/consistency-proof/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Entry Core v1](https://schema.kya-os.org/v1/protocol/audit/entry/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Producer Event v1](https://schema.kya-os.org/v1/protocol/audit/event/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Head Request v1](https://schema.kya-os.org/v1/protocol/audit/head-request/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS Audit Head Response v1](https://schema.kya-os.org/v1/protocol/audit/head-response/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS Audit Inclusion Proof Request v1](https://schema.kya-os.org/v1/protocol/audit/inclusion-proof-request/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS Audit Inclusion Proof Response v1](https://schema.kya-os.org/v1/protocol/audit/inclusion-proof-response/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS RFC 9162 Inclusion Proof v1](https://schema.kya-os.org/v1/protocol/audit/inclusion-proof/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Ingest Response v1](https://schema.kya-os.org/v1/protocol/audit/ingest-response/v1.0.0): A recorder's committed signed entry and receipt, with the verification outcomes established before acknowledgement.
- [KYA-OS Audit List Entries Request v1](https://schema.kya-os.org/v1/protocol/audit/list-entries-request/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS Audit List Entries Response v1](https://schema.kya-os.org/v1/protocol/audit/list-entries-response/v1.0.0): Wire envelope of the operator-facing audit read/replay API (SPEC-AUDIT-READ), matching the @kya-os/mcp 1.16.2 runtime contract (`@kya-os/mcp/audit` read-contract).
- [KYA-OS Independent Checkpoint Observation Receipt v1](https://schema.kya-os.org/v1/protocol/audit/observation/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Recorder Receipt Core v1](https://schema.kya-os.org/v1/protocol/audit/receipt/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Record](https://schema.kya-os.org/v1/protocol/audit/record/v1.0.0): Versioned, portable audit log record summarizing a single verified KYA-OS tool call. Provides a standard, cross-implementation format for compliance and non-repudiation trails (audit.v1).
- [KYA-OS Audit Replay Bundle v1](https://schema.kya-os.org/v1/protocol/audit/replay-bundle/v1.0.0): Portable signed-inventory audit replay bundle, matching the @kya-os/mcp v1.11.0 runtime contract.
- [KYA-OS Signed Audit Bundle Manifest v1](https://schema.kya-os.org/v1/protocol/audit/signed-bundle-manifest/v1.0.0): Replay-bundle manifest core, its digest, and exporter compact JWS, matching the @kya-os/mcp v1.11.0 runtime contract.
- [KYA-OS Signed Audit Checkpoint v1](https://schema.kya-os.org/v1/protocol/audit/signed-checkpoint/v1.0.0): RFC 9162 checkpoint core, its digest, and detached compact JWS, matching the @kya-os/mcp v1.11.0 runtime contract.
- [KYA-OS Signed Audit Entry v1](https://schema.kya-os.org/v1/protocol/audit/signed-entry/v1.0.0): Complete recorder-assigned audit entry envelope, matching the @kya-os/mcp v1.11.0 runtime contract.
- [KYA-OS Signed Audit Recorder Receipt v1](https://schema.kya-os.org/v1/protocol/audit/signed-receipt/v1.0.0): Recorder receipt core and its detached compact JWS, matching the @kya-os/mcp v1.11.0 runtime contract.
- [KYA-OS Out-of-Band Audit Verification Policy v1](https://schema.kya-os.org/v1/protocol/audit/verification-policy/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Audit Verification Report v1](https://schema.kya-os.org/v1/protocol/audit/verification-report/v1.0.0): JSON Schema draft 2020-12.
- [KYA-OS Needs-Authorization Error](https://schema.kya-os.org/v1/protocol/authorization/needs-authorization/v1.0.0): Error returned when a tool call requires user authorization. The response is itself signed (detached JWS in _meta) so the client can verify the authorizationUrl before trusting it; the client resumes the flow with resumeToken after the user grants authority (SPEC §9.2).
- [KYA-OS Delegation Credential](https://schema.kya-os.org/v1/protocol/delegation/credential/v1.0.0): W3C Verifiable Credential containing a KYA-OS delegation with CRISP constraints.
- [KYA-OS Delegation Credential (W3C VC 2.0 + ZCAP-LD profile)](https://schema.kya-os.org/v1/protocol/delegation/credential/v1.1.0): A W3C Verifiable Credential 2.0 whose credentialSubject IS an attenuated ZCAP-LD capability. One credential per delegation HOP; a chain runs root -> ... -> leaf. CRISP attenuation is enforced on resolve, fail-closed: a child's allowedAction MUST be a subset of its parent's; caveats are monotone-narrowing (child MaxAmount <= parent, child ValidUntil <= parent, and a parent caveat may never be silently dropped); the parent's delegate (invoker/controller) MUST be the child's issuer; child.parentCapability MUST reference the parent capability id; the invocationTarget is constant along the chain; depth <= 10; and the ROOT's parentCapability equals its invocationTarget with issuer/invocationTarget = the resource owner / resource. responsibleParty is recomputed as the issuer of the root credential; the leaf invoker is asserted equal to the per-request proof key. This schema is a re-profile of the prior draft, not a new artifact.
- [KYA-OS StatusList2021 Credential](https://schema.kya-os.org/v1/protocol/delegation/status-list/v1.0.0): W3C StatusList2021 Verifiable Credential used to publish delegation revocation or suspension state. The interoperable wire format for revocation when delegator and verifier are operationally decoupled (KYA-OS L3).
- [KYA-OS Handshake Request](https://schema.kya-os.org/v1/protocol/handshake/request/v1.0.0): Client-initiated handshake request to establish a KYA-OS session with nonce-based replay protection.
- [KYA-OS Handshake Response](https://schema.kya-os.org/v1/protocol/handshake/response/v1.0.0): Server response to a successful handshake request, establishing session context.
- [KYA-OS Entity Card](https://schema.kya-os.org/v1/protocol/identity/card/v1.1.0): A typed, DID-anchored identity card for a KYA-OS entity (mcp | agent | client | verifier | human). One canonical card is anchored by a `KyaOsEntityCard` service entry on the entity's did:web DID document and projected onto the four discovery surfaces the ecosystem already indexes (MCP server.json / catalog.json `_meta['org.kya-os/card']`, A2A AgentExtension, NANDA AgentFacts, and the MCP catalog entry). The card asserts identity + type + declared capabilities; everything trust-bearing (accountability, attested capabilities, KYC/KYB) is proven by referenced credentials, not self-claimed (claim-minimalism). The sender-constrained holder-of-key proof (`org.kya-os/proof.v1`) is NEVER on the static card — it rides per-request `_meta` on top (see detached-proof); `proofProfile` only names the profile a verifier should expect.
- [KYA-OS MCP Extension Settings](https://schema.kya-os.org/v1/protocol/mcp-extension/settings/v1.0.0): The settings object declared under capabilities.extensions["org.kya-os/decentralized-authority"] in MCP ClientCapabilities and ServerCapabilities (SEP-2133). All members are optional; an empty object means the extension is supported with default configuration. Unknown members are ignored for forward compatibility. See SPEC-MCP-EXTENSION.md section 3.
- [KYA-OS Detached Proof](https://schema.kya-os.org/v1/protocol/proof/detached/v1.0.0): Cryptographic proof binding an MCP tool request/response pair to an agent's identity and session context.
- [KYA-OS Detached Proof](https://schema.kya-os.org/v1/protocol/proof/detached/v1.1.0): Cryptographic proof binding an MCP tool request/response pair to an agent's identity and session context.
- [KYA-OS Discovery Document](https://schema.kya-os.org/v1/protocol/well-known/v1.0.0): Well-known discovery document served at /.well-known/mcp for KYA-OS service discovery.

## Reference

- [KYA-OS specification](https://kya-os.org/mcp)
- [schema-index.json](https://schema.kya-os.org/schema-index.json)
- [Donated core repository](https://github.com/decentralized-identity/kya-os-mcp)
## Frequently asked

### What is KYA-OS?

KYA-OS is an open protocol for verifiable AI-agent identity, delegation, and proof. It defines how an agent proves who it is and what authority it holds, enforceable at the edge and compatible with the web. The protocol is donated to the Decentralized Identity Foundation (DIF).

### How do I reference a KYA-OS schema?

Every schema is published at its canonical $id URL under schema.kya-os.org/v1/protocol/. Point a JSON Schema $ref or $schema field directly at that URL. All documents are served with open CORS and the application/schema+json content type, so validators and $ref resolvers can fetch them from any origin.

### What schema format is used?

Schemas are versioned (v1.0.0) JSON Schema documents, immutable at their $id: a published schema never changes in place, so consumers can pin a version with confidence. New revisions are published at a new version path rather than overwriting an existing one.

### Where is the KYA-OS specification?

The full protocol spec lives at [kya-os.org](https://kya-os.org), which spans every binding — MCP, HTTP, and more. For MCP specifically, see [kya-os.org/mcp](https://kya-os.org/mcp); its reference implementation and these schemas are in the donated core repo, [decentralized-identity/kya-os-mcp](https://github.com/decentralized-identity/kya-os-mcp).

Last updated: 2026-09-23