Schema Extensions

Reference for AdCP-specific x- prefixed schema annotations.

AdCP schemas carry several x- prefixed annotation keywords that supplement the JSON Schema vocabulary. JSON Schema validators ignore unknown x- keywords per draft-07 §6, so adding these keys is wire-compatible with any conforming validator.

This page is the canonical reference for those annotations. Codegen consumers (TypeScript / Python / Go type generators), the storyboard runner, and the AdCP SDK family read these annotations programmatically; verifiers MAY read them but the normative behavior they describe is also documented in the relevant section of security.mdx or the field’s own description.

x-status

Marks a schema or property as experimental — part of the core protocol but not yet frozen. Sellers implementing experimental surfaces declare the feature id in experimental_features on get_adcp_capabilities. See Experimental Status for the full graduation policy.

"trusted_match": {
  "type": "object",
  "x-status": "experimental",
  "description": "Trusted Match Protocol support..."
}

Allowed values: "experimental". The keyword is omitted on stable surfaces.

x-adcp-validation

Lifts structured normative constraints out of prose descriptions into a machine-readable shape. Storyboard runners and SDK validators consume the structured rules; codegen consumers can ignore the annotation and read the human description.

The keyword is most useful for fields whose description currently carries a “MUST be present when…” or “MUST equal the host of…” clause that the storyboard runner cannot enforce by parsing English.

Shape

"some_field": {
  "type": "string",
  "format": "uri",
  "description": "Brief one or two sentences for codegen JSDoc; full constraints live in x-adcp-validation and the linked spec.",
  "x-adcp-validation": {
    "trust_root": true,
    "required_when": { "any_of": [ ... ] },
    "schema_required_when": { ... },
    "verifier_constraints": { ... },
    "distinct_from": "other.field.path",
    "spec": "docs/.../section.mdx#anchor"
  }
}

Sub-keys

Key	Type	Purpose
trust_root	boolean	Field is load-bearing for signature verification; verifiers MUST treat as authoritative.
required_when	object wrapping any_of / all_of	Storyboard-enforced required-when rules (3.x). The object has exactly one of any_of (OR-joined) or all_of (AND-joined), each containing an array of leaf conditions. Each leaf is one of: { "field": "...", "non_empty": true }, { "field": "...", "equals": <value> }, { "field": "...", "any_subfield_present": true }. The wrapping object mirrors JSON Schema’s anyOf/allOf precedent so tooling readers can reuse familiar boolean-combinator semantics. Bare arrays are NOT accepted — always wrap.
schema_required_when	condition	When the rule promotes from storyboard-enforced to schema-required. Typically keyed on adcp.supported_versions matching a version pattern via any_item_matches_pattern (e.g., "^4\\." for the 4.0 cutover and any 4.x patch).
forbidden_when	object wrapping any_of / all_of	Inverse of required_when. The field MUST be absent (or false/empty, depending on type) when the wrapped condition holds. Same leaf shape as required_when. Use for fields whose presence is mutually exclusive with another posture.
disjoint_with	string (dotted path) or array of dotted paths	Item-level mutual exclusion: no value in this field’s array MAY appear in any of the named arrays. Storyboard runners assert set-disjointness on each. Example: request_signing.warn_for carries disjoint_with: "request_signing.required_for" because an operation can be in one or the other, never both.
subset_of	string (dotted path)	Item-level subset constraint: every value in this field’s array MUST also appear in the named array. Example: request_signing.required_for carries subset_of: "request_signing.supported_for" — an operation can’t be required without being supported.
verifier_constraints	object	Free-form key-value map of verifier-side rules that don’t fit the structured sub-keys above. Keys are normative (e.g., agent_url_match: "byte_equal"); the storyboard runner enforces these against test vectors. Prefer the structured sub-keys (required_when, forbidden_when, disjoint_with, subset_of) when they fit; reach for verifier_constraints only for one-off rules that don’t generalize.
distinct_from	string (dotted path)	Names another field that has a similar shape but different semantics, to defuse name confusion (e.g., identity.brand_json_url distinct from sponsored_intelligence.brand_url). Verifiers MUST NOT substitute one for the other.
spec	string (relative path with anchor)	Pointer to the normative section in the docs that defines the field’s full semantics. Always required when other sub-keys are present.

Conformance

• Validators MUST ignore unknown sub-keys for forward-compatibility (the schema may add new entries in a minor release).
• The storyboard runner consumes required_when, schema_required_when, and verifier_constraints to generate test cases per release; runners that don’t yet recognize a sub-key MUST skip it and emit an “unrecognized validation rule” warning.
• Codegen consumers (TypeScript / Python / Go type generators) MAY surface x-adcp-validation.spec as a @see JSDoc link but otherwise treat the annotation as opaque.

Current usage

Representative usage:

Field	Sub-keys used	Rule
identity.brand_json_url	trust_root, required_when, schema_required_when, verifier_constraints, distinct_from	Trust-root pointer for signing-key discovery; required-when tied to signing posture; schema-required in 4.0; distinct from sponsored_intelligence.brand_url. See security.mdx §Discovering an agent’s signing keys.
identity.key_origins	verifier_constraints (purpose_anchoring)	Every purpose listed MUST have a corresponding signing posture declared elsewhere on the response. Cross-field rule. See security.mdx §Origin separation.
request_signing.required_for	subset_of	Every operation listed MUST also appear in supported_for — an operation can’t be required without being supported.
request_signing.warn_for	disjoint_with, subset_of	An operation MUST NOT appear in both warn_for and required_for. Every operation listed MUST also appear in supported_for.
webhook_signing.supported	verifier_constraints (must_equal_when)	When the seller advertises mutating-webhook emission (media_buy.reporting_delivery_methods includes webhook OR media_buy.content_standards.supports_webhook_delivery: true), supported MUST be true. Closes a downgrade vector.
wholesale_feed_webhooks.event_types	verifier_constraints (wholesale_feed_webhook_capability_consistency)	product.* event types require wholesale get_products; signal.* event types require wholesale get_signals; wholesale_feed.bulk_change requires at least one declared wholesale repair path and must name only a repairable feed family.
get_products.wholesale_feed_version / get_signals.wholesale_feed_version	verifier_constraints (required_for_wholesale_request)	Version tokens are required on wholesale read responses, but the shared response schemas cannot infer the request’s buying_mode / discovery_mode from the response body alone.

Already enforced natively by JSON Schema and excluded from migration:

• adcp.idempotency — the discriminated oneOf already requires replay_ttl_seconds in the supported branch and forbids it in the unsupported branch.
• webhook_signing.algorithms — the enum: ["ed25519", "ecdsa-p256-sha256"] on each item already enforces the allowlist.

Migration history tracked at adcontextprotocol/adcp#3827.

x-adcp-open-payload

Classifies fields that look open-ended to SDK generators. The annotation is documentary and non-validating; the field’s JSON Schema still controls wire validation.

Allowed authoring values:

Value	Meaning for schema authors and generators
true	The field intentionally carries free-form payload data. Generators MAY model the object/decoded-JSON arm as Record<string, unknown> or another generic JSON container without warning.
Omitted	Unclassified. Generators and schema lint rules SHOULD NOT infer either true or false; they MAY warn on unannotated additionalProperties: true object fields during review.

false is reserved for a future structured-but-extension-tolerant marker. Source schemas MUST NOT set x-adcp-open-payload: false until the repository defines at least one canonical use site and the generator contract for that value.

For mixed fields, the annotation applies only to the object or decoded-JSON payload arm. Scalar arms still follow their declared schema. For example, an upstream recorded body may be a decoded JSON object when the content type is JSON-shaped and a string otherwise; x-adcp-open-payload: true marks the decoded JSON payload as intentionally open, not the string arm as an object model.

"breakdown": {
  "type": "object",
  "x-adcp-open-payload": true,
  "additionalProperties": true
}

Use omission for legacy or not-yet-classified fields; do not use omission to mean “closed”.

x-adcp-hoist

Build-time directive that marks a source schema as a canonically shared type. The schema bundler hoists every inline occurrence into a single root $defs entry and replaces inline copies with $ref pointers; the directive itself is stripped from bundled output. Wire-irrelevant — validators MUST ignore it (draft-07 §6 unknown-keyword semantics) and conforming consumers SHOULD NOT observe it on bundled artifacts.

{
  "$id": "/schemas/core/price-block.json",
  "title": "Price Block",
  "x-adcp-hoist": true,
  "type": "object",
  "properties": {
    "cpm": { "type": "number" },
    "currency": { "type": "string" }
  }
}

Why opt-in for complex objects

Pure enums hoist automatically (see hoistDuplicateInlineEnums) because merging two structurally-identical enums is semantics-preserving. Complex objects are different — structural identity ≠ semantic identity. BriefAsset (proposed creative spec) and VASTAsset (delivered video creative) currently share fields but represent different lifecycle concepts; auto-merging them would create cross-tool coupling the source schemas don’t express, and would be hard to unwind once SDKs codegen against the merged type. x-adcp-hoist makes the share-or-split decision deliberate per schema.

Bundler behavior

• Hoists at any occurrence count (≥1). The directive declares intent — “this is a canonical named type” — so adding a second reference later never changes the codegen surface.
• title is required. Missing or empty title → build-time error. The directive is meant to be deliberate.
• Same title + different shape is a build-time error. Two marked schemas authored with the same title but distinct fields would otherwise silently suffix one to Foo2, defeating the directive’s “canonical name” guarantee.
• Collision with a pre-existing $defs key is suffixed (PriceBlock2), matching the convention used by the pure-enum hoist.
• Stripped from bundled output — both from the canonical $defs entry and from any stray marker that was authored inside a pre-existing $defs block.

SDK / codegen impact

Adding x-adcp-hoist to a previously-inlined source schema is wire-compatible (the bundled schema still validates the same payloads) but is a codegen-shape change: TypeScript / Python / Go type generators that previously emitted an anonymous inline type (often Foo1, Foo2, …) will now emit a single named type. SDK adopters maintain rename aliases per their own deprecation policy — see adcp-client#942 for the client-side rename/alias tracking.

Conformance

• Validators MUST ignore x-adcp-hoist per draft-07 §6 (unknown keywords are tolerated). The directive has no wire semantics.
• Source-tree consumers (third parties that dereference static/schemas/source/... directly rather than the bundled artifacts) MUST treat x-adcp-hoist: true as a no-op annotation. The schema’s content is the contract.
• Bundlers other than scripts/build-schemas.cjs MAY honor the directive or ignore it; a bundler that ignores it produces a wire-compatible bundle with un-deduped inline copies.

History

• Introduced in #4557. Successor to #3145 phase 2.

Future extensions

New x-adcp-* keywords are added in minor releases. Consumers MUST tolerate unknown x- keywords without erroring. The convention reserves the x-adcp- namespace; vendor-specific or deployment-specific annotations SHOULD use a vendor-specific prefix (e.g., x-yourorg-) to avoid collision.