contextgraph-envelope.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://contextgraphprotocol.org/schema/v1/contextgraph-envelope.schema.json",
  "title": "Context Graph Protocol envelope",
  "description": "A single Context Graph Protocol message \u2014 the unit exchanged on the wire (one object per NDJSON line over stdio, one request/response body over streamable HTTP). An envelope is an internally-tagged enum: the `type` field selects the variant and sits at the same level as the payload fields. Validate one message at a time against this root schema; validate individual payloads against the entries in `$defs`.",
  "$comment": "This schema is the AUTHORING-STRICT profile: `additionalProperties: false` throughout, so it catches typos in fixtures and reference messages. It is NOT the interop contract. Per SPEC.md \u00a713 U1, a receiver on the wire MUST ignore unrecognised members rather than reject the message \u2014 that is what lets a contextgraph/1.x minor add optional fields a 1.0 peer harmlessly drops. Do not use this schema to reject a peer's live message solely for carrying unknown members; use it to lint what you author.",
  "oneOf": [
    {
      "$ref": "#/$defs/Handshake"
    },
    {
      "$ref": "#/$defs/HandshakeAck"
    },
    {
      "$ref": "#/$defs/Query"
    },
    {
      "$ref": "#/$defs/Frames"
    },
    {
      "$ref": "#/$defs/Verify"
    },
    {
      "$ref": "#/$defs/Verified"
    },
    {
      "$ref": "#/$defs/Shutdown"
    },
    {
      "$ref": "#/$defs/Error"
    }
  ],
  "$defs": {
    "versionString": {
      "type": "string",
      "pattern": "^contextgraph/[0-9]+\\.[0-9]+(-draft)?$",
      "description": "Context Graph Protocol version string. Grammar: contextgraph/MAJOR.MINOR with an optional -draft suffix. Two versions interoperate iff they share a major family (the substring up to the first dot)."
    },
    "Handshake": {
      "type": "object",
      "description": "host -> provider. The host names the protocol version it speaks.",
      "properties": {
        "type": {
          "const": "handshake"
        },
        "protocol_version": {
          "$ref": "#/$defs/versionString"
        }
      },
      "required": [
        "type",
        "protocol_version"
      ],
      "additionalProperties": false
    },
    "HandshakeAck": {
      "type": "object",
      "description": "provider -> host. The provider replies with its own version, identity, and capabilities. If data_flow.egress is true, a conforming host MUST NOT auto-enable this provider.",
      "properties": {
        "type": {
          "const": "handshake_ack"
        },
        "protocol_version": {
          "$ref": "#/$defs/versionString"
        },
        "provider": {
          "$ref": "#/$defs/ProviderInfo"
        },
        "capabilities": {
          "$ref": "#/$defs/Capabilities"
        },
        "attester_keys": {
          "type": "array",
          "items": { "$ref": "#/$defs/AttesterKey" },
          "description": "Public keys this provider signs its provenance attestations with (SPEC.md §6.5). Absent or empty means the provider offers no attestation, which is conformant: §6.5 makes the construction mandatory and the signing optional."
        }
      },
      "required": [
        "type",
        "protocol_version",
        "provider",
        "capabilities"
      ],
      "additionalProperties": false
    },
    "Query": {
      "type": "object",
      "description": "host -> provider. A retrieval request carrying a hard token budget (max_tokens).",
      "properties": {
        "type": {
          "const": "query"
        },
        "query": {
          "$ref": "#/$defs/ContextQuery"
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Correlation id; a provider MUST echo it on the reply (SPEC.md H4)."
        }
      },
      "required": [
        "type",
        "query"
      ],
      "additionalProperties": false
    },
    "Frames": {
      "type": "object",
      "description": "provider -> host. The answer: a ContextQueryResult whose frames' token_cost MUST sum to at most the query's max_tokens.",
      "properties": {
        "type": {
          "const": "frames"
        },
        "result": {
          "$ref": "#/$defs/ContextQueryResult"
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Correlation id; a provider MUST echo it on the reply (SPEC.md H4)."
        }
      },
      "$comment": "There is NO attestations member here. Detached provenance evidence rides result.frame_attestations and result.result_attestation, and nowhere else (SPEC.md §6.5.5, ADR 0014). This envelope briefly carried a second copy; two encodings of one signature with no tie-breaking rule is the defect the protocol exists to prevent, and an in-process provider that never builds an envelope must still be able to sign what it serves. See #161.",
      "required": [
        "type",
        "result"
      ],
      "additionalProperties": false
    },

    "AttesterKey": {
      "type": "object",
      "description": "A public key a provider publishes at the handshake so a verifier can check the attestations it serves (SPEC.md §6.5.4). A construction anchor, not a trust anchor: a key handed over by the party being audited settles whether an attestation is BUILT correctly, never who signed it.",
      "properties": {
        "key_id": {
          "type": "string",
          "minLength": 1,
          "description": "Matches ProvenanceAttestation.key_id. Rotation is a new id, never a reused one."
        },
        "algorithm": {
          "type": "string",
          "minLength": 1,
          "description": "The scheme this key is for, e.g. `ed25519`. A string rather than an enum so a post-quantum successor is additive."
        },
        "public_key": {
          "type": "string",
          "pattern": "^[0-9a-f]+$",
          "description": "The raw public key, lowercase hex — the encoding ProvenanceAttestation.signature already uses."
        }
      },
      "required": ["key_id", "algorithm", "public_key"],
      "additionalProperties": false
    },

    "Verify": {
      "type": "object",
      "description": "host -> provider. Revalidate frames the host already holds (context/verify, docs/context-reuse.md §4). Carries frame identities only — NEVER frame bodies, so verification costs bytes rather than tokens. Capability-gated: a host sends this only to a provider whose handshake advertised capabilities.verify.",
      "properties": {
        "type": { "const": "verify" },
        "request": { "$ref": "#/$defs/VerifyRequest" }
      },
      "required": ["type", "request"],
      "additionalProperties": false
    },

    "Verified": {
      "type": "object",
      "description": "provider -> host. One verdict per frame identity the provider is answering for (docs/context-reuse.md §4). No frame bodies travel here either; a stale verdict may carry the replacement DIGEST, never the replacement content.",
      "properties": {
        "type": { "const": "verified" },
        "response": { "$ref": "#/$defs/VerifyResponse" }
      },
      "required": ["type", "response"],
      "additionalProperties": false
    },

    "Shutdown": {
      "type": "object",
      "description": "host -> provider. No payload. A well-behaved provider exits cleanly (stdio) or expects no further requests (HTTP).",
      "properties": {
        "type": {
          "const": "shutdown"
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    },
    "Error": {
      "type": "object",
      "description": "provider -> host. Report a problem without crashing. A provider that exits on a bad request fails the malformed-input-tolerance conformance check.",
      "properties": {
        "type": {
          "const": "error"
        },
        "message": {
          "type": "string",
          "minLength": 1
        },
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Correlation id; a provider MUST echo it on the reply (SPEC.md H4)."
        },
        "code": {
          "type": "string",
          "description": "Machine-readable error classification (SPEC.md Errors). The vocabulary is OPEN: an unrecognised code MUST be treated as `internal`, which is why this is not an enum \u2014 constraining it would make adding a code a breaking change.",
          "examples": [
            "bad_request",
            "unsupported_kind",
            "budget_unsatisfiable",
            "unavailable",
            "shutting_down",
            "internal"
          ]
        }
      },
      "required": [
        "type",
        "message"
      ],
      "additionalProperties": false
    },

    "FrameId": {
      "type": "object",
      "description": "The stable identity of one frame's exact content bytes: (provider id, frame id, content digest). The spine shared by deterministic composition, usage reports, and context/verify (docs/context-reuse.md §1).",
      "properties": {
        "provider_id": { "type": "string", "minLength": 1 },
        "frame_id": { "type": "string", "minLength": 1 },
        "content_digest": {
          "type": ["string", "null"],
          "$comment": "Provider-declared and opaque. Absent ⇒ the frame is not verifiable and a host re-queries it rather than reusing it unchecked (§1 D4)."
        }
      },
      "required": ["provider_id", "frame_id"],
      "additionalProperties": false
    },

    "VerifyRequest": {
      "type": "object",
      "description": "The frame identities a host asks a provider to revalidate. Identities only — no frame bodies (docs/context-reuse.md §4).",
      "properties": {
        "frames": {
          "type": "array",
          "items": { "$ref": "#/$defs/FrameId" },
          "$comment": "A host SHOULD only include identities carrying a content_digest; a digest-less frame cannot be revalidated and is re-queried instead."
        }
      },
      "required": ["frames"],
      "additionalProperties": false
    },

    "VerdictStatus": {
      "enum": ["valid", "stale", "gone", "unknown"],
      "description": "A provider's answer for one frame (docs/context-reuse.md §4). `valid` — content unchanged, the host MAY keep reusing the body it holds. `stale` — the frame exists but its content changed; the host MUST NOT keep serving its copy. `gone` — the frame no longer exists, and re-querying this identity is pointless. `unknown` — the provider cannot say; the host MUST NOT read this as validity. A host reuses a frame ONLY on `valid`: reuse requires a positive answer, never the absence of a negative one."
    },

    "FrameVerdict": {
      "type": "object",
      "description": "One frame's verdict, flattened onto the identity it answers. The identity is echoed in FULL rather than implied by position, so a host correlates by matching and a provider that reorders, omits, or duplicates entries cannot shift a `valid` onto the wrong frame. An identity that comes back with no entry is treated as `unknown` — silence is not validity.",
      "properties": {
        "frame": { "$ref": "#/$defs/FrameId" },
        "status": { "$ref": "#/$defs/VerdictStatus" },
        "replacement_digest": {
          "type": ["string", "null"],
          "$comment": "Only meaningful with status `stale`: the provider's CURRENT digest for the frame, offered so a host can tell what it would be re-fetching. A digest, never a body. Optional — a provider that knows the content changed but not what it is now still answers `stale` honestly."
        }
      },
      "required": ["frame", "status"],
      "additionalProperties": false
    },

    "VerifyResponse": {
      "type": "object",
      "description": "A provider's answer to a VerifyRequest (docs/context-reuse.md §4).",
      "properties": {
        "verdicts": {
          "type": "array",
          "items": { "$ref": "#/$defs/FrameVerdict" }
        }
      },
      "required": ["verdicts"],
      "additionalProperties": false
    },

    "DataFlow": {
      "type": "object",
      "description": "Declares what a provider does with data. `egress` is the security-critical field: a conforming host gates egress providers behind recorded, named consent. `egress_scopes` (optional) classes WHERE content goes, for scope-level consent receipts.",
      "properties": {
        "reads": {
          "type": "boolean"
        },
        "writes": {
          "type": "boolean"
        },
        "egress": {
          "type": "boolean"
        },
        "egress_scopes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EgressScope"
          },
          "$comment": "Optional (omitted when empty). Each entry is one of the four base scopes or a namespaced custom scope. An off-machine scope (anything but local-only) alongside egress:false is a conformance failure (docs/context-reuse.md §3, C5)."
        }
      },
      "required": [
        "reads",
        "writes",
        "egress"
      ],
      "additionalProperties": false
    },
    "EgressScope": {
      "type": "string",
      "description": "Where a provider's served content may go (docs/context-reuse.md §3). One of the four normative base classes, or a namespaced custom scope (vendor:scope-name, a ':' with non-empty sides).",
      "anyOf": [
        {
          "enum": [
            "local-only",
            "org-tenant",
            "third-party-index",
            "third-party-model"
          ]
        },
        {
          "pattern": "^[^:]+:[^:]+"
        }
      ]
    },
    "ProviderInfo": {
      "type": "object",
      "description": "Provider identity + declared data-flow direction, surfaced at consent time.",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1
        },
        "version": {
          "type": "string",
          "minLength": 1
        },
        "data_flow": {
          "$ref": "#/$defs/DataFlow"
        }
      },
      "required": [
        "name",
        "version",
        "data_flow"
      ],
      "additionalProperties": false
    },
    "QueryCapability": {
      "type": "object",
      "description": "The retrieval surface a provider offers: the frame kinds it serves.",
      "properties": {
        "kinds": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "kinds"
      ],
      "additionalProperties": false
    },
    "Capabilities": {
      "type": "object",
      "description": "What a provider can do: query kinds, request correlation, graph support, and the embedding space it indexes. Every field is a capability a host can actually exercise (ADR 0004).",
      "properties": {
        "query": {
          "$ref": "#/$defs/QueryCapability"
        },
        "correlation": {
          "type": "boolean",
          "description": "Provider echoes a request's `id` on its reply, enabling pipelining (SPEC.md H4)."
        },
        "graph": {
          "type": "boolean"
        },
        "embeddings_fingerprint": {
          "type": [
            "string",
            "null"
          ],
          "description": "Embedding space identity: <model-id>/<dimensions>[/<normalization>] (SPEC.md E1).",
          "pattern": "^[^/]+/[0-9]+(/[^/]+)?$"
        },
        "verify": {
          "type": "boolean",
          "$comment": "Whether the provider answers context/verify (docs/context-reuse.md §4). Optional and defaults to false, so a pre-§4 provider is treated as unsupported and the host falls back to re-querying."
        },
        "representations": {
          "type": "array",
          "items": { "$ref": "#/$defs/Representation" },
          "$comment": "Frame representations this provider can return. Absent/empty ⇒ full only (the legacy default). Advertising compact or reference requires resolve: true."
        },
        "resolve": {
          "type": "boolean",
          "$comment": "Whether the provider answers context/resolve for a frame's content_ref. Compact/reference support implies resolve support."
        }
      },
      "required": [
        "query"
      ],
      "additionalProperties": false
    },
    "ContextQuery": {
      "type": "object",
      "description": "A retrieval request. max_tokens is a hard contract, not a hint.",
      "properties": {
        "goal": {
          "type": "string",
          "minLength": 1
        },
        "query_text": {
          "type": [
            "string",
            "null"
          ]
        },
        "embedding": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "number"
          }
        },
        "kinds": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FrameKind"
          }
        },
        "anchors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "max_frames": {
          "$ref": "#/$defs/u32"
        },
        "max_tokens": {
          "$ref": "#/$defs/u32"
        },
        "as_of": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
          "description": "RFC 3339 UTC timestamp, uppercase T and Z (SPEC.md F4)."
        },
        "representation_preferences": {
          "type": "array",
          "items": { "$ref": "#/$defs/Representation" },
          "$comment": "Ordered preference; the provider returns the first representation it supports. Absent/empty ⇒ [full]."
        }
      },
      "required": [
        "goal",
        "max_frames",
        "max_tokens"
      ],
      "$comment": "Required is exactly what the reference serializer (contextgraph-types ContextQuery) always emits: goal, max_frames, max_tokens. `kinds` and `anchors` are skip_serializing_if=Vec::is_empty in the reference type, so an unfiltered, unanchored query — the most common query there is, and the one the conformance suite's own sample_query() sends — serializes without them. Listing them as globally required made that query un-representable in conformant JSON, the same class of bug ADR 0006 surfaced on ContextFrame. An empty array remains valid; absence and [] mean the same thing (no filter).",
      "additionalProperties": false
    },
    "ContextQueryResult": {
      "type": "object",
      "description": "The response to a query. truncated is true if more candidates existed than fit the budget.",
      "properties": {
        "frames": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ContextFrame"
          }
        },
        "truncated": {
          "type": "boolean"
        },
        "dropped_estimate": {
          "$ref": "#/$defs/u32Nullable"
        },
        "frame_attestations": {
          "type": "array",
          "items": { "$ref": "#/$defs/FrameAttestation" },
          "$comment": "Detached per-frame evidence (SPEC.md §6.5.5, F11). Optional and omitted when empty, so an unsigned answer is byte-identical to one from a provider written before attestation existed. It sits BESIDE the frames, never inside one (F6), so re-signing and key rotation cannot perturb a frame's content-addressed identity."
        },
        "result_attestation": {
          "$ref": "#/$defs/ProvenanceAttestation",
          "$comment": "One signature over the whole answer (SPEC.md §6.5.3, F12): signed_commitment is the RFC 6962 Merkle root over the commitments of EXACTLY the frames carried in `frames`, in the canonical FrameId order of §6.3 — never over a larger candidate set the provider truncated away."
        }
      },
      "required": [
        "frames",
        "truncated"
      ],
      "additionalProperties": false
    },

    "ProvenanceAttestation": {
      "type": "object",
      "description": "A detached signature over a commitment to a frame's identity and its provenance chain (SPEC.md §6.5). Optional: a conformant provider may serve none and a conformant host may verify none. What is NOT optional is the construction — an attestation that exists must be computed exactly as §6.5.1-§6.5.3 specify, or two implementations disagree about whether the same evidence is genuine.",
      "properties": {
        "signed_commitment": {
          "type": "string",
          "pattern": "^sha256:[0-9a-f]{64}$",
          "$comment": "The commitment this signature covers: a §6.5.2 frame_commitment on a FrameAttestation entry, or a §6.5.3 merkle_root on result_attestation (F7). Lowercase hex is mandated, not conventional — digests are compared byte-for-byte and a case disagreement is indistinguishable from tampering."
        },
        "key_id": {
          "type": "string",
          "minLength": 1,
          "$comment": "Rotation is expressed by a NEW key_id, never by reusing one, so an archived attestation always names the exact key that produced it."
        },
        "algorithm": {
          "type": "string",
          "minLength": 1,
          "$comment": "AUTHORING LINT ONLY, and deliberately not an enum. A verifier that does not recognise the value reports it as uncheckable and declines (F8) — 'I cannot check this' is never 'this is good'. Freezing the set would make adopting a post-quantum scheme a breaking wire change.",
          "examples": ["ed25519"]
        },
        "attester_id": {
          "type": "string",
          "minLength": 1,
          "$comment": "The accountable authority, as distinct from the key that mechanically produced the signature."
        },
        "signature": {
          "type": "string",
          "pattern": "^[0-9a-f]+$",
          "$comment": "Lowercase hex, matching the sha256:<hex> convention every other digest in this protocol already uses. The length is algorithm-dependent and therefore not constrained here; an ed25519 signature is 128 hex characters."
        },
        "issued_at": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
          "description": "RFC 3339 UTC timestamp, uppercase T and Z (SPEC.md F4)."
        }
      },
      "required": [
        "signed_commitment",
        "key_id",
        "algorithm",
        "attester_id",
        "signature",
        "issued_at"
      ],
      "additionalProperties": false
    },

    "InclusionStep": {
      "type": "object",
      "description": "One level of a Merkle inclusion proof: the sibling subtree hash and which side it sits on. RFC 6962 lets a verifier recover the side from index arithmetic; CGP states it instead, so an off-by-one in a hand-written verifier produces a WRONG ROOT rather than a silently-accepted proof.",
      "properties": {
        "sibling": {
          "type": "string",
          "pattern": "^sha256:[0-9a-f]{64}$"
        },
        "sibling_is_left": { "type": "boolean" }
      },
      "required": ["sibling", "sibling_is_left"],
      "additionalProperties": false
    },

    "InclusionProof": {
      "type": "object",
      "description": "A proof that one frame commitment is a leaf of the signed result_attestation root (SPEC.md §6.5.3). This is what makes a signed answer selectively disclosable: a host proves one frame was in the set without revealing the others.",
      "properties": {
        "leaf_index": { "type": "integer", "minimum": 0 },
        "leaf_count": {
          "type": "integer",
          "minimum": 1,
          "$comment": "Part of the proof because a root alone does not pin the tree's SIZE, and a verifier that ignores it can be shown a proof from a differently-shaped tree."
        },
        "path": {
          "type": "array",
          "items": { "$ref": "#/$defs/InclusionStep" },
          "$comment": "Sibling hashes from the leaf upward. Empty for a single-leaf tree — a lone leaf needs no siblings."
        }
      },
      "required": ["leaf_index", "leaf_count", "path"],
      "additionalProperties": false
    },

    "FrameAttestation": {
      "type": "object",
      "description": "What a result set says about one frame's attestation (SPEC.md §6.5.5, F11). The identity is echoed in FULL rather than implied by array position, for the reason FrameVerdict already echoes it: a provider that reorders, omits, or duplicates entries cannot shift one frame's evidence onto another. It is also what a verifier needs — provider_id and content_digest are two of the three inputs to the frame commitment and are recoverable from nowhere else.",
      "properties": {
        "frame": { "$ref": "#/$defs/FrameId" },
        "attestation": {
          "$ref": "#/$defs/ProvenanceAttestation",
          "$comment": "A detached signature over this frame's own §6.5.2 commitment. Absent when the provider signed only the result-set root: the frame is then attested THROUGH inclusion_proof, which is the cheapest honest shape — one signature instead of n."
        },
        "inclusion_proof": {
          "$ref": "#/$defs/InclusionProof",
          "$comment": "Optional (F13), and the reason is a host that keeps a SUBSET: once frames are dropped their sibling commitments are gone and the root can never be recomputed. A host retaining part of a signed answer derives and keeps the proofs before dropping the rest. See ADR 0014."
        }
      },
      "required": ["frame"],
      "anyOf": [
        { "required": ["attestation"] },
        { "required": ["inclusion_proof"] }
      ],
      "$comment": "An entry with neither a signature nor a proof names a frame and asserts nothing about it. This schema is authoring-strict, so it is rejected here; on the wire a host treats such an entry as unattested (F9) rather than rejecting the message.",
      "additionalProperties": false
    },

    "FrameKind": {
      "type": "string",
      "enum": [
        "snippet",
        "symbol",
        "fact",
        "doc",
        "memory",
        "episode",
        "graph"
      ],
      "$comment": "AUTHORING LINT, NOT THE INTEROP CONTRACT. These are the base kinds of contextgraph/1.0; the closed enum exists so a typo in a fixture ('dcc') fails CI. On the wire the vocabulary is OPEN: SPEC.md §13 U2 requires a receiver to accept an unrecognised kind (most likely one added by a later 1.x), treat the frame as opaque evidence, and preserve the original string verbatim if it re-emits the frame. Do NOT use this schema to validate messages from a peer — rejecting a frame here would break the family's no-flag-day guarantee. See contextgraph_types::FrameKind::Unknown."
    },

    "Representation": {
      "type": "string",
      "enum": ["full", "compact", "reference"],
      "$comment": "How a frame carries content. Absent on the wire ⇒ full. full inlines content; compact inlines a transformed rendering plus a resolver handle; reference carries no inline content, only a content_ref and canonical hash."
    },

    "ContentFidelity": {
      "type": "string",
      "enum": ["exact", "normalized", "summarized", "omitted"],
      "$comment": "Fidelity of carried content relative to the source. Absent ⇒ exact for a legacy full frame."
    },

    "InlineContentRequirement": {
      "type": "string",
      "enum": ["required", "resolvable_reference_allowed"]
    },

    "ContentRef": {
      "type": "object",
      "description": "An opaque resolver handle for a compact/reference frame's content. content_ref.uri is distinct from ContextFrame.uri (the source resource); provider_id names the exact provider that returned the frame so a fan-out host routes context/resolve back to it.",
      "properties": {
        "provider_id": { "type": "string", "minLength": 1 },
        "uri": { "type": "string", "minLength": 1 },
        "expires_at": { "type": ["string", "null"] }
      },
      "required": ["provider_id", "uri"],
      "additionalProperties": false
    },

    "Transform": {
      "type": "object",
      "description": "The transformation a compact frame applied to its source, so a consumer knows what it is reading.",
      "properties": {
        "method": { "type": "string", "minLength": 1 },
        "implementation": { "type": "string", "minLength": 1 },
        "version": { "type": "string", "minLength": 1 }
      },
      "required": ["method", "implementation", "version"],
      "additionalProperties": false
    },

    "ContextFrame": {
      "type": "object",
      "description": "The unit of exchange. A frame is not a string \u2014 it is a structured record of relevance, cost, provenance, and validity. content is untrusted data: a conforming host delimits it as quoted material and never executes it.",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "$ref": "#/$defs/FrameKind"
        },
        "title": {
          "type": "string",
          "minLength": 1
        },
        "content": {
          "type": "string"
        },
        "content_digest": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "$comment": "Provider-declared, opaque digest of the frame's content bytes (e.g. sha256:<hex>) \u2014 the third component of the frame's stable FrameId identity. Optional: a frame without one is not verifiable and a host re-queries it (docs/context-reuse.md \u00a71, \u00a74)."
        },
        "uri": {
          "type": [
            "string",
            "null"
          ]
        },
        "representation": {
          "$ref": "#/$defs/Representation",
          "$comment": "How the frame carries content. Absent ⇒ full (legacy); full frames omit this field on the wire."
        },
        "content_fidelity": { "$ref": "#/$defs/ContentFidelity" },
        "canonical_content_hash": {
          "type": "string",
          "minLength": 1,
          "$comment": "SHA-256 over the complete source content bytes — distinct from content_digest (the inline-content hash). Required for compact/reference frames."
        },
        "content_ref": { "$ref": "#/$defs/ContentRef" },
        "transform": { "$ref": "#/$defs/Transform" },
        "minimum_content_fidelity": { "$ref": "#/$defs/ContentFidelity" },
        "inline_content_requirement": { "$ref": "#/$defs/InlineContentRequirement" },
        "score": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "token_cost": {
          "$ref": "#/$defs/u32"
        },
        "canonical_token_cost": {
          "$ref": "#/$defs/u32",
          "$comment": "Token cost of the complete canonical source content, produced by an actual tokenizer (unlike the byte-formula token_cost, §B3/§7.2). If canonical_token_cost is present, tokenizer_ref SHOULD name the tokenizer that produced it."
        },
        "tokenizer_ref": { "type": "string", "minLength": 1 },
        "valid_from": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
          "description": "RFC 3339 UTC timestamp, uppercase T and Z (SPEC.md F4)."
        },
        "valid_to": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
          "description": "RFC 3339 UTC timestamp, uppercase T and Z (SPEC.md F4)."
        },
        "recorded_at": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$",
          "description": "RFC 3339 UTC timestamp, uppercase T and Z (SPEC.md F4)."
        },
        "provenance": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Provenance"
          }
        },
        "citation_label": {
          "type": [
            "string",
            "null"
          ],
          "minLength": 1,
          "$comment": "Optional in the wire type (Option<String>), but the frame-validity conformance check requires a non-empty citation_label. A provider MUST include one to pass conformance."
        },
        "embedding": {
          "$ref": "#/$defs/FrameEmbeddingNullable"
        },
        "relations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Relation"
          }
        }
      },
      "required": ["id", "kind", "title", "score", "token_cost"],
      "$comment": "Required is exactly what the reference serializer (contextgraph-types ContextFrame) always emits: id, kind, title, score, token_cost. content is governed per-representation by the allOf below. provenance and relations are skip_serializing_if=Vec::is_empty in the reference type and are required by no frame-validity check (SPEC.md F1-F5), so a conformant frame may omit them when empty — listing them as globally required contradicted the canonical serializer (ADR 0006 surfaced this: it is the first Rust-serialized frame producer validated against this schema).",
      "allOf": [
        {
          "$comment": "reference: no inline content, content_digest, or transform; a resolver handle and canonical hash are required.",
          "if": {
            "properties": { "representation": { "const": "reference" } },
            "required": ["representation"]
          },
          "then": {
            "required": ["content_ref", "canonical_content_hash"],
            "not": {
              "anyOf": [
                { "required": ["content"] },
                { "required": ["content_digest"] },
                { "required": ["transform"] }
              ]
            }
          }
        },
        {
          "$comment": "compact: inline content plus inline hash, canonical hash, transform identity, and resolver handle.",
          "if": {
            "properties": { "representation": { "const": "compact" } },
            "required": ["representation"]
          },
          "then": {
            "required": ["content", "content_digest", "canonical_content_hash", "transform", "content_ref"]
          }
        },
        {
          "$comment": "full (including legacy frames with no representation field): inline content is required.",
          "if": {
            "not": {
              "properties": { "representation": { "enum": ["compact", "reference"] } },
              "required": ["representation"]
            }
          },
          "then": { "required": ["content"] }
        }
      ],
      "additionalProperties": false
    },
    "Provenance": {
      "type": "object",
      "description": "An origin entry for a frame. NOTE: the Rust field is named `kind`, but it serializes to `type` on the wire.",
      "properties": {
        "type": {
          "type": "string",
          "minLength": 1
        },
        "uri": {
          "type": [
            "string",
            "null"
          ]
        },
        "range": {
          "type": [
            "string",
            "null"
          ]
        },
        "digest": {
          "type": [
            "string",
            "null"
          ],
          "pattern": "^sha256:[0-9a-f]{64}$",
          "description": "Content digest: sha256:<64 lowercase hex> (SPEC.md F5)."
        },
        "method": {
          "type": [
            "string",
            "null"
          ]
        },
        "by": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "type"
      ],
      "additionalProperties": false
    },
    "Relation": {
      "type": "object",
      "description": "A graph edge. A relation is surfaced by its human display_name, never a raw target id.",
      "properties": {
        "rel": {
          "type": "string",
          "minLength": 1
        },
        "target_uri": {
          "type": "string",
          "minLength": 1
        },
        "display_name": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "rel",
        "target_uri"
      ],
      "additionalProperties": false
    },
    "FrameEmbedding": {
      "type": "object",
      "description": "A frame embedding. The vector payload itself is elidable; fingerprint is the stable identifier.",
      "properties": {
        "fingerprint": {
          "type": "string",
          "minLength": 1
        },
        "vector": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "number"
          }
        }
      },
      "required": [
        "fingerprint"
      ],
      "additionalProperties": false
    },
    "FrameEmbeddingNullable": {
      "oneOf": [
        {
          "$ref": "#/$defs/FrameEmbedding"
        },
        {
          "type": "null"
        }
      ]
    },
    "u32": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4294967295
    },
    "u32Nullable": {
      "oneOf": [
        {
          "$ref": "#/$defs/u32"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}