The AdCP schema registry

AdCP is the Ad Context Protocol, an open standard for software agents that discover inventory and buy media: a buying agent on one side of the wire, a publisher's or platform's sales agent on the other. Every message they exchange has a JSON Schema file behind it, and the release 3.1.13 tree holds 761 of them.

Schema trees

static/schemas/source/ is what the build reads. dist/schemas/<version>/ is what it writes, and dist/schemas/latest.json points at the current stable release, currently 3.1.13. That pointer carries five keys: latest, latest_stable, channel, path and index. The source tree carries a version stamp of its own, bumped only when a release is cut, so for most of a release cycle it names a version that shipped weeks earlier.

Two things exist only in the output tree: the dereferenced bundled/ copies, and manifest.json. Neither is visible when browsing the source tree on GitHub.

index.json and manifest.json

The two registry files describe the same release from different angles, and each omits operations the other carries. The operation list is the union of the two. Where both name the same tool they point at the same request and response schema, so the disagreement is entirely about what each file leaves out. Neither file references the other, and nothing in the build compares them.

Nothing at the call site declares which of the two list_creative_formats contracts applies. That comes from get_adcp_capabilities, whose supported_protocols array says whether the agent speaks media_buy or creative. Without that call there is no fallback check: both request schemas require nothing and set additionalProperties to true, so the wrong variant validates clean and the fields the receiving agent does not recognise are discarded without an error.

How a reference resolves

Every cross-file reference in a published release is an absolute, version-pinned URL path. The tree contains no relative paths. The source tree writes those same references without the version segment, so a resolver configured against GitHub source and then aimed at a release fetches paths that do not exist — every reference, not some of them. Resolving a published reference means mapping the /schemas/<version>/ prefix onto the release directory.

// dist/schemas/3.1.13/media-buy/get-products-request.json
{ "$ref": "/schemas/3.1.13/core/version-envelope.json" }
//   -> dist/schemas/3.1.13/core/version-envelope.json

// static/schemas/source/media-buy/get-products-request.json
{ "$ref": "/schemas/core/version-envelope.json" }
//   -> static/schemas/source/core/version-envelope.json

The shared envelopes

core/version-envelope.json declares two properties, adcp_version and adcp_major_version, is referenced by 137 files, and requests and responses compose it alike. core/protocol-envelope.json declares the rest: status, context_id, task_id, message, timestamp, payload and the async plumbing. 68 response schemas compose it and no request schema does, so a response schema inherits those fields before declaring any of its own.

Schemas with no inbound reference

Some files in the release are reachable from neither registry file nor from any $ref. Every file in error-details/ is one, and so is every file in core/async-response-refs/, which holds one copy of each async arm the manifest already names under a different path. Nothing points at either set, so nothing makes them mandatory. creative/creative-purged-webhook.json is unreferenced for a different reason: it describes a payload that arrives out of band, and a webhook body has nothing to $ref it.

Absence from index.json does not imply absence from the reference graph. formats/canonical/image.json has no entry in the index, and neither do video_hosted, html5, audio_daast or the other nine files in that directory. They are reachable two hops down: core/product-format-declaration.json refs formats/canonical/image.json, which refs formats/canonical/_base.json.

Error detail schemas

enums/error-code.json defines 92 error codes. error-details/ holds 15 schemas, one per shape those errors can take. No $ref edge joins the two files.

core/error.json is referenced by 67 schemas, more than any of the domain objects it sits alongside, and it declares details as a bare object of no particular shape, with no $ref and no discriminator. The link between a code and its detail schema lives in an enumDescriptions string, in markdown backticks. For VERSION_UNSUPPORTED: "The error details SHOULD follow error-details/version-unsupported.json". Other codes carry a pointer written the same way. A draft-07 validator applies no constraint from enumDescriptions, so the pointer has no effect on validation.

The same file carries the structured form of that pattern for a different case. Next to enumDescriptions sits an enumMetadata block whose $comment reads: "SDKs MUST consume this block instead of parsing 'Recovery: X' from enumDescriptions prose." enumMetadata carries recovery hints as structured data; the error-detail schema pointers remain in enumDescriptions prose.

Mapping a code to its detail schema is therefore a manual step. enumDescriptions names six of the fifteen outright. The other nine mappings are stated nowhere; the filename and the code name correspond by convention only. The map from code to detail schema exists in no release artefact, so a new code or a changed mapping is not detectable from a release diff.

discriminator under draft-07

42 schemas in the release use discriminator to say which branch of a oneOf applies. discriminator is an OpenAPI keyword, draft-07 does not define it, and a draft-07 validator therefore ignores it and evaluates every branch. Validation outcome is unchanged, because the nine branches under core/pricing-option.json each pin pricing_model with a const. Error output is not: an invalid pricing_model returns one failure per branch, nine in place of the single branch failure that was intended. A client that needs the intended diagnostic selects the branch on pricing_model itself and reports only that branch's errors.

Bundled schemas

docs/building/by-layer/L0/schemas.mdx directs tools that cannot resolve $ref to the bundled schemas, which have every reference inlined. That page states that all request and response task schemas are bundled. The table on the same page names eight bundled/ directories and omits brand/, collection/, account/ and governance/. The release ships those eight, so the sentence overstates the coverage.

23 of the 64 operations have no bundle: every brand-protocol operation, every collection-list operation, every account operation, the four governance plan operations, both serve-time operations and comply_test_controller. None of the 20 async response arms are bundled either. An integration built against brand rights or account financials without a $ref-resolving validator has no offline schema to load for those operations.

The 10 core objects

These are the domain nouns the operations pass around. They are not the schemas that hold the reference tree together: the most-referenced files in the release are extension, envelope and error scaffolding. media_buy_id appears in schemas across the release, while core/media-buy.json itself is referenced once, because a media buy is fetched by identifier rather than passed around.

A client author's checklist

• Read dist/schemas/<version>/, not static/schemas/source/. The two trees write $ref differently and a resolver tuned for one returns 404 on the other.
• Take the operation list as the union of index.json and manifest.json, and resolve the schema paths through the index.
• Call get_adcp_capabilities before list_creative_formats. Nothing else identifies which of the two contracts is in force, and neither request schema rejects the wrong payload.
• Resolve $ref in the client rather than loading bundled/. For 23 of the 64 operations no bundle exists.
• Hold the error-code to error-details/ map, all 15 entries, in client source, and diff it against enums/error-code.json on every release.

Related

• All 64 AdCP operations
• Discovery files: adagents.json and brand.json
• AAMP's schemas, which ship no registry index at all