# 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.

- **Format:** JSON Schema draft 2020-12
- **Protocol version:** v1
- **Schemas published:** 8
- **Specification:** https://kya-os.org/mcp
- **Source:** https://github.com/decentralized-identity/kya-os-mcp
- **Updated:** 2026-06-10

## Published schemas

### Handshake

- **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.

### Proof

- **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.

### Delegation

- **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 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).

### Authorization

- **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).

### Audit

- **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).

### Discovery

- **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.

## 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).