Schemas and Errors
Inventory of the Chio JSON Schema set, the error-code registry, any IETF protocol drafts, and the versioning policy that governs compatibility across schema, capability, receipt, and manifest revisions.
Source
This page reflects the contents of spec/schemas/, spec/errors/, spec/ietf/, and spec/versions/ in the chio repository. The schema set is the source of truth for the Chio v1 wire contract; SDKs, codegen pipelines, and conformance harnesses resolve types from these files first and treat hand-typed bindings as derived artifacts.
Current schema bundle version: 1.0.0 (spec/schemas/VERSION).
Schemas
Schemas live under three trees: chio-wire/v1/ for the native framed transport, chio-http/v1/ for the hosted HTTP surface, and a small set of top-level schemas for cross-cutting artifacts. Every JSON Schema is draft 2020-12.
chio-wire/v1/agent
Messages an agent sends to the kernel.
| File | Scope |
|---|---|
agent/heartbeat.schema.json | Liveness ping from agent |
agent/list_capabilities.schema.json | Request the kernel's capability list view |
agent/tool_call_request.schema.json | Invoke a tool under a presented capability |
chio-wire/v1/kernel
Messages the kernel sends back.
| File | Scope |
|---|---|
kernel/capability_list.schema.json | Capability inventory response |
kernel/capability_revoked.schema.json | Notification of revocation propagation |
kernel/heartbeat.schema.json | Liveness ping from kernel |
kernel/tool_call_chunk.schema.json | Streaming chunk for an in-flight tool call |
kernel/tool_call_response.schema.json | Final tool-call response with signed receipt |
chio-wire/v1/result
Tool-call result variants embedded in tool_call_response.
| File | Scope |
|---|---|
result/ok.schema.json | Successful invocation |
result/stream_complete.schema.json | Stream finished after one or more chunks |
result/cancelled.schema.json | Caller-cancelled invocation |
result/incomplete.schema.json | Partial result without a clean terminal state |
result/err.schema.json | Error result envelope |
chio-wire/v1/error
Error code + detail shapes used inside err.schema.json. Each schema pins the discriminating code string and the structured detail body.
| File | Scope |
|---|---|
error/capability_denied.schema.json | Capability presented but denied by signature, scope, or subject binding |
error/capability_expired.schema.json | Capability past its validity window |
error/capability_revoked.schema.json | Capability matched a revocation entry |
error/policy_denied.schema.json | Guard pipeline denied with named guard and reason |
error/tool_server_error.schema.json | Tool server failure |
error/internal_error.schema.json | Kernel-internal failure (fail-closed) |
chio-wire/v1/capability
Capability primitives backing the authority model in protocol section 3. The Rust types live in crates/chio-core-types/src/capability.rs; schemas mirror them and are validated against every case in tests/bindings/vectors/capability/v1.json.
| File | Scope |
|---|---|
capability/token.schema.json | Canonical issued CapabilityToken |
capability/grant.schema.json | Single grant carried inside a token's scope (ToolGrant, ResourceGrant, PromptGrant via oneOf) |
capability/revocation.schema.json | Single RevocationRecord (wire companion to the kernel revocation notification) |
chio-wire/v1/receipt
Receipt primitives for the audit log; mirror ChioReceipt and MerkleProof in crates/chio-core-types/. Validated against tests/bindings/vectors/receipt/v1.json on every PR; M04 deterministic-replay consumes them as the golden-bundle contract.
| File | Scope |
|---|---|
receipt/record.schema.json | Signed receipt envelope (Decision, ToolCallAction, GuardEvidence) |
receipt/inclusion-proof.schema.json | Merkle inclusion artifact proving membership in the receipt-log tree |
chio-wire/v1/jsonrpc
JSON-RPC 2.0 framing used by the hosted MCP HTTP edge and the A2A peer transports. Wire-compatible with the JSON-RPC 2.0 specification. Chio-specific extensions appear only in the error-code registry and recognized notification method names; field shapes remain canonical JSON-RPC 2.0.
| File | Scope |
|---|---|
jsonrpc/request.schema.json | Correlated call (requires id and method) |
jsonrpc/response.schema.json | Success or error reply (requires id plus exactly one of result or error via oneOf) |
jsonrpc/notification.schema.json | Fire-and-forget message (requires method, forbids id) |
chio-wire/v1/trust-control
Trust-control plane primitives anchoring protocol section 9. The four schemas describe the lifecycle envelope of one operator-visible authority lease.
| File | Scope |
|---|---|
trust-control/lease.schema.json | Authority lease projection (mirrors ClusterAuthorityLeaseView) |
trust-control/heartbeat.schema.json | Lease refresh request |
trust-control/terminate.schema.json | Voluntary lease release request |
trust-control/attestation.schema.json | Normalized runtime attestation evidence statement (mirrors RuntimeAttestationEvidence) |
Pre-pin status
heartbeat and terminate are drafted from PROTOCOL.md prose and the lease lifecycle paths in the trust-control implementation; dedicated request structs are expected to land alongside the cluster RPC formalization in M09 P3, at which point these schemas will be re-pinned to the live serde shapes.chio-wire/v1/provenance
Provenance-graph primitives for the M07 tool-call fabric.
| File | Scope |
|---|---|
provenance/stamp.schema.json | M07 ProvenanceStamp (provider, request_id, api_version, principal, received_at) |
provenance/context.schema.json | Mirrors GovernedCallChainContext |
provenance/attestation-bundle.schema.json | Ordered list of normalized attestation evidence bound to a governed chainId |
provenance/verdict-link.schema.json | Binds a Chio policy verdict back to the provenance graph via requestId, optional receiptId, and chainId |
chio-http/v1
Hosted HTTP surface schemas. See the HTTP substrate reference.
| File | Scope |
|---|---|
caller-identity.schema.json | Caller identity envelope (bearer hash, API key hash, anonymous) |
chio-http-request.schema.json | HTTP request projection used during evaluation |
error-envelope.schema.json | Structured HTTP error body (chio_access_denied and friends) |
evaluate-request.schema.json | Sidecar evaluator request body |
evaluate-response.schema.json | Sidecar evaluator response body |
http-receipt.schema.json | HTTP receipt fields (route_pattern, verdict, evidence, policy_hash, kernel_key) |
session-init.schema.json | MCP session initialize |
session-resume.schema.json | MCP session resume |
stream-frame.schema.json | Hosted stream frame envelope |
verdict.schema.json | Tagged-union verdict (allow or deny with reason and guard) |
Top-level schemas
| File | Scope |
|---|---|
chio-tee-frame-v1.json | TEE attestation frame envelope (top-level under spec/schemas/) |
receipt-provenance-v1.json | Provenance overlay for receipt records |
chio-replay-report/v1.schema.json | Replay report envelope used by deterministic replay tooling |
Manifest and Coverage
spec/schemas/MANIFEST.sha256: per-file SHA-256 manifest covering every schema in the bundle. Every PR that adds or changes a schema MUST update this manifest.spec/schemas/COVERAGE.md: hand-curated audit checklist tracking the M01 Phase 1 schema-add work. Phase 1 target: at least 35 wire schemas underchio-wire/v1/and at least 10 underchio-http/v1/.spec/schemas/VERSION: current bundle version (currently1.0.0).
Errors
The error code taxonomy lives in spec/errors/chio-error-registry.v1.json (schema id chio.error-registry.v1). Codes are grouped by category; each entry carries a numeric code, a stable name, the category, a transient flag, retry guidance, and (where applicable) a jsonrpcCode or nativeWireName tying the registry entry to a specific wire schema.
Categories
protocol, auth, capability, guard, budget, tool, internal.
Error Codes
| Code | Name | Category | Transient | Retry strategy | Wire mapping |
|---|---|---|---|---|---|
| 1000 | protocol_version_unsupported | protocol | no | do_not_retry_until_version_change | JSON-RPC -32600 |
| 1001 | session_not_initialized | protocol | no | reinitialize | JSON-RPC -32002 |
| 1002 | invalid_request_shape | protocol | no | do_not_retry | JSON-RPC -32600 |
| 1100 | auth_missing_or_invalid | auth | yes | retry_after_refresh | -- |
| 2100 | capability_denied | capability | no | do_not_retry | native capability_denied |
| 2101 | capability_expired | capability | no | retry_after_reissue | native capability_expired |
| 2102 | capability_revoked | capability | no | retry_after_reissue | native capability_revoked |
| 3100 | guard_denied | guard | no | do_not_retry | native policy_denied |
| 4100 | budget_exhausted | budget | yes | retry_after_budget_change | -- |
| 5100 | tool_server_error | tool | yes | retry_with_backoff | native tool_server_error |
| 6100 | internal_error | internal | yes | retry_with_backoff | native internal_error |
When Each Error Is Emitted
protocol_version_unsupported: peer requested a version outside the supported set; on native this triggers transport close, on hosted MCP this is a JSON-RPC error.session_not_initialized: caller invoked an operation beforeinitialize. Resolution: open a new session and rerun initialize.invalid_request_shape: the request fails JSON-RPC framing or schema validation. Resolution: fix the shape; do not retry as-is.auth_missing_or_invalid: hosted edge or trust-control credential is absent or invalid. Resolution: refresh credentials.capability_denied: capability presented but rejected (signature, scope, subject binding). Resolution: do not retry the same capability.capability_expired: capability past validity. Resolution: obtain a fresh capability.capability_revoked: capability matched a revocation entry. Resolution: obtain a newly issued capability; the revoked one MUST NOT be retried.guard_denied: guard pipeline denied with a named guard and reason. Resolution: adjust the request or policy inputs before retrying.budget_exhausted: budget guard denied. Resolution: retry only after replenishment, grant widening, or billing reconciliation.tool_server_error: tool server failed. Resolution: bounded exponential backoff unless upstream tooling documents a permanent failure.internal_error: kernel-internal failure. Resolution: bounded backoff; escalate if persistent.
Wire mapping
nativeWireName map directly to the matching schema under chio-wire/v1/error/. The native channel surfaces the structured detail body; consumers MUST use both the numeric code and the code string when classifying errors.IETF Drafts
The repository includes one IETF Internet-Draft.
| Document | Status | Scope |
|---|---|---|
spec/ietf/draft-chio-protocol-00.md | draft (April 2026, expires October 2026) | Protocol and runtime profile for mediated tool execution under signed capabilities, signed receipts, explicit versioning, and bounded transport security. Defines the native framed transport, the MCP-compatible hosted edge, and the trust-control lifecycle endpoints. Intended status: Standards Track. |
The draft references this repository's machine-readable registries directly: spec/versions/chio-protocol-negotiation.v1.json and spec/errors/chio-error-registry.v1.json. It cites RFC 8785 (JSON Canonicalization) and RFC 9449 (DPoP) as normative references, and lists GNAP, SCITT, RATS, W3C Verifiable Credentials, OID4VCI, and OID4VP as informative references.
Versioning
Chio versioning policy is published in spec/versions/chio-protocol-negotiation.v1.json (schema id chio.protocol-negotiation.v1). It defines exact-match compatibility and rejection behavior across the three protocol surfaces.
Per-Surface Rules
| Surface | Mechanism | Compatibility | Rejection behavior |
|---|---|---|---|
| Native Chio | Out-of-band exact match on wire version chio-wire-v1 | exact match; no in-band downgrade | Transport close_or_reset_transport; Chio error 1000 |
| Hosted MCP | initialize.params.protocolVersion echoed in result.protocolVersion; MCP-Protocol-Version session header | exact match from supported set; supported versions: ["2025-11-25"] | JSON-RPC -32600; Chio error 1000 |
| Trust-control | Path prefix /v1 | exact prefix match | Standard 404; downgrade behavior not applicable |
Schema, Capability, Receipt, and Manifest Versioning
- Schema bundle: pinned by
spec/schemas/VERSION(currently1.0.0) and the per-filespec/schemas/MANIFEST.sha256. SDKs and codegen pipelines validate against the bundle. - Capability tokens: the schema is
chio.capability-token.v1; canonical fields are pinned bycapability/token.schema.json. - Receipts: the schema is
chio.receipt.v1; bridged invocations MUST use the same schema so the receipt log remains uniform. - Manifests: the schema is
chio.manifest.v1; the OpenAPI bridge MUST emit a manifest that conforms to it.
Compatibility Policy
- Additive fields MAY appear in JSON responses and signed artifacts; consumers MUST tolerate unknown fields.
- Schema identifiers (
chio.*.v1) are exact-match. Unknown schema identifiers for schema-tagged artifacts MUST be rejected. - Fail-closed behavior is part of the protocol contract, not an implementation detail; downgrade or speculative compatibility is not part of the contract.
- Wire-version negotiation on the native surface is intentionally narrow (exact match, no downgrade). Operators upgrading the wire version run kernels and agents on the new wire in lockstep.
Related
- Protocol: capability, receipt, and manifest contracts.
- Wire protocol: native framed transport and message families.
- Bindings API: vector corpus and binding-conformance suite.
- Receipt format.
- Policy schema.
- HTTP substrate.