AdCP — Schemas

The L0 wire layer is JSON-over-HTTP framed by published JSON Schemas. This page is the reference for getting the schemas — where they live, how to pin a version, how to verify supply-chain provenance, and the directory shape inside a release. If you’re picking an SDK rather than the schemas themselves, see Choose your SDK.

Schema access

AdCP schemas are available from two sources:

Source	URL	Best For
Website	`https://adcontextprotocol.org/schemas/v3/`	Runtime fetching, version aliases
GitHub	`https://github.com/adcontextprotocol/adcp/tree/main/dist/schemas`	Offline access, CI/CD pipelines

Both sources contain identical schemas. The GitHub repository includes all released versions with bundled schemas committed directly to the codebase.

One-shot protocol bundle

Syncing hundreds of individual schema files adds up. Every AdCP release also publishes a single gzipped tarball containing the complete protocol — schemas, compliance storyboards, and the OpenAPI registry — so clients can pull one artifact instead of crawling the tree.

Path	Contents	Notes
`https://adcontextprotocol.org/protocol/latest.tgz`	Current development bundle	Changes with every merge
`https://adcontextprotocol.org/protocol/{version}.tgz`	Pinned release bundle	Immutable once published
`https://adcontextprotocol.org/protocol/{version}.tgz.sha256`	SHA-256 checksum	Use to verify download integrity
`https://adcontextprotocol.org/protocol/{version}.tgz.sig`	Sigstore detached signature	Use to verify publisher identity. Present only when the release was cut via the `release.yml` workflow — absent for out-of-band republishes.
`https://adcontextprotocol.org/protocol/{version}.tgz.crt`	Fulcio-issued signing certificate	Pairs with `.sig` for `cosign verify-blob`. Present only when the release was cut via the `release.yml` workflow — absent for out-of-band republishes.

Every tarball extracts into a single adcp-{version}/ directory (safe extraction, no tarbomb). Inside:

adcp-{version}/
  README.md               # quickstart + links
  CHANGELOG.md            # release notes
  manifest.json           # version, generated_at, contents summary
  schemas/                # full JSON schema tree (same as /schemas/{version}/)
  compliance/             # protocols/, specialisms/, universal/, test-kits/, index.json
  openapi/registry.yaml   # OpenAPI description

Verify the checksum before extracting:

curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz.sha256
shasum -a 256 -c 3.1.0.tgz.sha256
tar xzf 3.1.0.tgz
cd adcp-3.1.0

Pull it once per version, cache by SHA, and you have everything needed to validate requests, run storyboards, and render documentation offline. The @adcp/sdk sync-schemas command uses this under the hood. Available tarballs are also listed at /protocol/.

Verifying protocol bundle signatures

The SHA-256 sidecar lives on the same origin as the tarball, so it only protects against in-transit tampering. For supply-chain protection — proving the bundle came from the AdCP release workflow and was not swapped for a malicious one even if the host were compromised — every released {version}.tgz is also published with a Sigstore detached signature. The signature is produced by the GitHub Actions release workflow using keyless OIDC: there is no long-lived AdCP signing key to leak. The certificate binds the signature to the workflow identity that issued it.

# Pull the tarball and the two signature sidecars
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz.sig
curl -OL https://adcontextprotocol.org/protocol/3.1.0.tgz.crt

# Verify (requires cosign 2.x — `brew install cosign`)
cosign verify-blob \
  --signature 3.1.0.tgz.sig \
  --certificate 3.1.0.tgz.crt \
  --certificate-identity-regexp '^https://github\.com/adcontextprotocol/adcp/\.github/workflows/release\.yml@refs/(heads|tags)/.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  3.1.0.tgz

cosign verify-blob exits non-zero if the signature was made by anything other than the AdCP release workflow, even if the SHA matches and TLS is valid. Use this in any pipeline that ingests the protocol bundle as an enforcement source. The @adcp/sdk, adcp-client-python, and adcp-go SDKs perform this verification automatically when the sidecars are present. The refs/(heads|tags)/.* wildcard is intentional — releases sign during the push-triggered workflow run, so the cert subject names the release branch (e.g. refs/heads/3.0.x for v3.0.1+, refs/heads/main for v3.0.0). The trust gate is upstream release.yml’s on.push.branches allowlist, not the consumer’s regex. Literal-allowlist regexes ((main|2\.6\.x)-style) silently break every time a new maintenance branch is added — see Verifying protocol tarballs for the full trust model and the cert-subject-by-release lookup. Older releases that predate signing, and versions republished out of band (bypassing the signing workflow), remain checksum-only — clients should treat missing sidecars as a “checksum-only” trust level rather than a verification failure.

Compliance storyboards

Storyboards live alongside schemas at /compliance/{version}/. They define the test scenarios AAO runs to verify an agent’s capability claims.

Path	Purpose
`/compliance/{version}/universal/`	Required for every agent (capability discovery, error handling, schema validation)
`/compliance/{version}/protocols/{protocol}/`	Baseline required to claim a protocol (`media-buy`, `creative`, `signals`, `governance`, `brand`, `sponsored-intelligence`)
`/compliance/{version}/specialisms/{id}/`	Optional specialization claims (e.g. `sales-guaranteed`, `sales-broadcast-tv`)
`/compliance/{version}/index.json`	Enumerates available protocols, specialisms, and universal storyboards

Declare supported_protocols (for protocol baselines) and specialisms (for narrow capability claims) in get_adcp_capabilities — the compliance runner executes the matching bundles to verify. See the full Compliance Catalog for every protocol and specialism an agent can claim.

Common schemas

Schema	URL
Product	`https://adcontextprotocol.org/schemas/v3/core/product.json`
Media Buy	`https://adcontextprotocol.org/schemas/v3/core/media-buy.json`
Creative Format	`https://adcontextprotocol.org/schemas/v3/core/format.json`
Schema Registry	`https://adcontextprotocol.org/schemas/v3/index.json`

For AI coding agents: point your coding agent to https://docs.adcontextprotocol.org/mcp for MCP integration documentation.

Schema versioning

AdCP uses semantic versioning. Choose the right path for your use case:

Path	Example	Best For
Exact version	`/schemas/3.0.0/`, `/compliance/3.0.0/`, `/protocol/3.0.0.tgz`	Production, SDK generation
Major version	`/schemas/v3/`, `/compliance/v3/`	Development, documentation
Minor version	`/schemas/v3.0/`, `/compliance/v3.0/`	Stable development (patch updates only)

The same version semantics apply to /schemas, /compliance, and /protocol/{version}.tgz — one release cuts all three.

Production (recommended)

Pin to an exact version for stability:

const SCHEMA_VERSION = '3.0.0';
const schema = await fetch(
  `https://adcontextprotocol.org/schemas/${SCHEMA_VERSION}/core/product.json`
);

Development

Use the major version alias to stay current with backward-compatible updates:

const schema = await fetch(
  'https://adcontextprotocol.org/schemas/v3/core/product.json'
);

SDK type generation

# TypeScript
npx json-schema-to-typescript \
  https://adcontextprotocol.org/schemas/3.0.0/core/product.json \
  --output types/product.d.ts

# Python
datamodel-codegen \
  --url https://adcontextprotocol.org/schemas/3.0.0/core/product.json \
  --output models/product.py

Bundled schemas

For tools that don’t support $ref resolution, use bundled schemas with all references resolved inline. Bundled schemas are available from both the website and GitHub:

Website access

https://adcontextprotocol.org/schemas/3.0.0/bundled/media-buy/create-media-buy-request.json

GitHub access

Bundled schemas are committed to the repository at dist/schemas/{VERSION}/bundled/:

# Clone and access locally
git clone https://github.com/adcontextprotocol/adcp.git
ls adcp/dist/schemas/3.0.0/bundled/media-buy/

# Or fetch directly via GitHub raw
curl https://raw.githubusercontent.com/adcontextprotocol/adcp/main/dist/schemas/3.0.0/bundled/media-buy/get-products-request.json

Directory structure

dist/schemas/{VERSION}/
├── bundled/                      # Fully dereferenced schemas
│   ├── media-buy/                # Media buying tasks
│   ├── creative/                 # Creative tasks
│   ├── signals/                  # Signal protocol tasks
│   ├── property/                 # Property/governance tasks
│   ├── content-standards/        # Content standards tasks
│   ├── sponsored-intelligence/   # Sponsored intelligence tasks
│   ├── protocol/                 # Protocol tasks
│   └── core/                     # Core task schemas
├── core/                         # Modular schemas with $ref
├── media-buy/
└── index.json                    # Schema registry

Bundled schema categories

All request/response task schemas are bundled:

Category	Tasks
`bundled/media-buy/`	get-products, create-media-buy, update-media-buy, list-creative-formats, sync-creatives, build-creative, list-creatives, get-media-buy-delivery, list-authorized-properties, provide-performance-feedback
`bundled/creative/`	list-creative-formats, preview-creative
`bundled/signals/`	get-signals, activate-signal
`bundled/property/`	create-property-list, get-property-list, list-property-lists, update-property-list, delete-property-list, validate-property-delivery
`bundled/content-standards/`	create-content-standards, get-content-standards, list-content-standards, update-content-standards, calibrate-content, validate-content-delivery, get-media-buy-artifacts
`bundled/sponsored-intelligence/`	si-get-offering, si-initiate-session, si-send-message, si-terminate-session
`bundled/protocol/`	get-adcp-capabilities
`bundled/core/`	tasks-get, tasks-list

See the schema registry for all available schemas.

Version discovery

# Get the full semver of the published schema bundle.
# (Note: `published_version` carries full semver including patch.
# It's distinct from the per-request/response wire `adcp_version`
# field defined in core/version-envelope.json, which uses
# release-precision — never send `published_version` on the wire.)
curl https://adcontextprotocol.org/schemas/v3/index.json | jq '.published_version'

Check Release Notes for version history and migration guides.

Registry API

The AgenticAdvertising.org registry provides a public REST API for brand resolution, property resolution, agent discovery, and authorization validation. No authentication required.

Registry API Reference

Resolve brands, discover agents, and validate authorization via REST.

Documentation Index

​Schema access

​One-shot protocol bundle

​Verifying protocol bundle signatures

​Compliance storyboards

​Common schemas

​Schema versioning

​Production (recommended)

​Development

​SDK type generation

​Bundled schemas

​Website access

​GitHub access

​Directory structure

​Bundled schema categories

​Version discovery

​Registry API

Registry API Reference

Schema access

One-shot protocol bundle

Verifying protocol bundle signatures

Compliance storyboards

Common schemas

Schema versioning

Production (recommended)

Development

SDK type generation

Bundled schemas

Website access

GitHub access

Directory structure

Bundled schema categories

Version discovery

Registry API