Schemas and Errors

Source

This page reflects the contents of spec/schemas/, spec/errors/, spec/ietf/, and spec/versions/ in the chio repository. The schema set defines the Chio v1 wire contract; SDKs, codegen pipelines, and conformance harnesses resolve types from these files first and treat hand-typed bindings as derived bindings.

Current schema bundle version: 1.0.0 (spec/schemas/VERSION).

Schemas

spec/schemas/ holds more than twenty schema families. The two documented in full below are the ones agents and sidecars parse directly: chio-wire/v1/ for the native framed transport and chio-http/v1/ for the hosted HTTP interface. The rest cover the wider protocol interfaces — among the larger ones chio-pheromone/v1, chio-runtime/v1, chio-federation/v1, chio-commerce/v1, chio-transaction/v1, chio-attest/v1, and chio-swarm/v1 — alongside chio-trust/v1, chio-proof-room/v1, chio-web3/v1, chio-disclosure/v1, chio-lineage/v1, chio-oracle/v1, chio-risk/v1, chio-enterprise/v1, chio-agent-web/v1, chio-transparency/v1, chio-workflow/v1, and chio-crypto/v1 (a single verification-context schema). Outside the wire and HTTP trees sit the one-file chio-replay-report/ family (chio-replay-report/v1.schema.json, the report shape emitted by chio replay --json) and a set of top-level schemas for shared objects. Full per-file tables for every family live in spec/schemas/COVERAGE.md. Every JSON Schema is draft 2020-12.

chio-wire/v1/agent

Messages an agent sends to the kernel.

chio-wire/v1/kernel

Messages the kernel sends back.

chio-wire/v1/result

Tool-call result variants embedded in tool_call_response.

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.

chio-wire/v1/capability

Capability primitives backing the authority model in protocol section 3. The Rust types live in crates/core/chio-core-types/src/capability.rs; schemas mirror them and are validated against every case in tests/bindings/vectors/capability/v1.json.

chio-wire/v1/receipt

Receipt primitives for the audit log; mirror ChioReceipt and MerkleProof in crates/core/chio-core-types/. Validated against tests/bindings/vectors/receipt/v1.json on every PR; M04 deterministic-replay consumes them as the golden-bundle contract.

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.

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.

chio-wire/v1/provenance

Provenance-graph types for the M07 tool-call graph.

chio-wire/v1/federation

Bilateral signature-slice envelopes for cross-kernel cosignature.

chio-wire/v1/anchor

Backs the accepts_anchor_batch_v1 federated capability-negotiation feature bit.

chio-http/v1

Hosted HTTP API schemas. See the HTTP sidecar reference.

Top-level schemas

Loose schema files at the root of spec/schemas/, covering cross-cutting artifacts that do not belong to a single family.

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: a coverage map of the shipped schema families as they exist today, not a planning document. It tables every file per family; the current map records forty schema files across eleven subtrees under chio-wire/v1/ and ten under chio-http/v1/. Update it whenever a schema is added, removed, or renamed.
• spec/schemas/VERSION: current bundle version (currently 1.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, transaction.

Error Codes

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 before initialize. 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.
• transaction_* (7100–7113): the Transaction Passport verifier rejected a governed transaction because a bound artifact failed a schema, hash, graph-closure, binding, evidence, settlement, or transparency check. All fourteen are non-transient (do_not_retry) and carry entry-specific guidance — for example, 7100 transaction_passport_schema_unsupported resolves by regenerating the passport with a registered transaction passport schema, and 7102 transaction_graph_not_closed by including every required evidence, claim-set, policy, and receipt node in the transaction graph. Resolution: correct or rebind the failing evidence, then resubmit the transaction as a fresh proof.

URN Error Registry

A second, more granular registry lives in spec/errors/registry.yaml (schema id chio.error-urn-registry.v1, version 0.1.0), with spec/errors/registry.schema.json pinning its shape. Every entry is addressed by a stable URN of the form urn:chio:error:<domain>:<code>. It currently defines 104 codes across 20 domains.

Domains carry a class. Core domains are populated today: capability, policy, guard, attest, replay, provider, manifest, kernel, transport, mobile, cli, custody, weights, and transaction. Reserved domains are declared but not yet populated, holding namespace for future work: delegation, adversarial, threat, arena, economy, and lineage.

Each entry carries:

• urn and domain: the addressable identity and its owning domain.
• severity: one of info, warning, error, or fatal.
• summary and help: the human-readable condition and the operator remediation.
• string_code: the stable machine token (for example CHIO-TRANSACTION-PASSPORT-SCHEMA-UNSUPPORTED).
• jsonrpc_code (optional): the numeric code when the same condition also surfaces over JSON-RPC.
• since and stability: the introducing version and one of stable, unstable, or deprecated.
• consumed_by: the crates that emit or classify against the entry.

IETF Drafts

The repository includes one IETF Internet-Draft.

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

Schema, Capability, Receipt, and Manifest Versioning

• Schema bundle: pinned by spec/schemas/VERSION (currently 1.0.0) and the per-file spec/schemas/MANIFEST.sha256. SDKs and codegen pipelines validate against the bundle.
• Capability tokens: the schema is chio.capability.v1; canonical fields are pinned by capability/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.
• The protocol requires fail-closed behavior. It does not define downgrade or speculative compatibility.
• 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.