Documentation Index

Fetch the complete documentation index at: https://docs.adcontextprotocol.org/llms.txt

Use this file to discover all available pages before exploring further.

​

Canonical Formats (preview)

TL;DR for adopters reading cold:

• 7 of 12 canonical formats ship stable at 3.1 GA (image, display_tag, video_hosted, video_vast, audio_hosted, audio_daast, native_in_feed — all re-encodings of IAB / VAST / DAAST / IAB OpenRTB Native 1.2). 5 stay preview past GA (html5, image_carousel, sponsored_placement, responsive_creative, agent_placement).
• v1 named formats stay first-class through 4.x with a 5.0 sunset floor. Dual-emission is the migration mode; SDKs translate either direction. Realistic v2-only buyer-agent timing is 4.x at the earliest.
• 15 v1→v2 mapping registry entries at GA, 71+ of audited v1 formats are v1-only out of the gate (need seller canonical field or registry PR to project to v2). v2-aware buyers see meaningfully thinner inventory than v1-aware ones through 3.x. Dual-read codepath realistic through 3.3.
• Phase 4 (SDK codegen) is the gating dependency for adopter consumption. Schemas are shippable today; the typed-tagged-union ergonomics this design earns land fully only with codegen. The runtime Ajv validator is the load-bearing gate — generated TS/Pydantic types lose if/then narrowing on format_kind: "custom" and result_kind.

Status: Preview track. The canonical-formats surface is being designed in flight against RFC #3305 and the #3307 implementation branch. Naming note: This work was originally drafted as “creative formats v2” — the v1↔v2 contrast describes the two format-authoring models (legacy named-format registry vs new canonical formats on products). To avoid collision with AdCP-the-protocol’s own version numbering (currently 3.x), file paths, identifiers, and the body of this doc use canonical formats terminology. The v1↔v2 contrast is reserved as schema-description shorthand where it disambiguates the two authoring paths on Product.format_ids vs Product.format_options.

​

Glossary

​

Architectural shift

​

The 12 canonical formats

​

experimental — one field, both axes

​

Two axes: composition (per-impression) vs production (who renders)

• deterministic — buyer can predict per-slot rendering. The surface serves what it received. (image, video_hosted, audio_hosted, video_vast, audio_daast, sponsored_placement.)
• algorithmic — surface picks combinations from a buyer-supplied asset pool per-impression. The buyer ships a pool; the surface composes. (responsive_creative for Google PMax / Meta Advantage+; agent_placement for AI-surface composition.)

• asset_source on image, video_hosted, audio_hosted — single shared 5-value enum: buyer_uploaded | publisher_host_recorded | seller_pre_rendered_from_brief | seller_human_designed | agent_synthesized. publisher_host_recorded is audio-specific (podcast host-read pattern) and meaningful only on audio_hosted.
• item_production_model on sponsored_placement — same axis, 4-value subset (drops publisher_host_recorded), applied per catalog item (the multi-output generative case: 1 brief × N catalog items → N rendered creatives)

​

Tracker assembly under seller-rendered sources

• Macro-substituted tracking (default). The seller honors AdCP universal_macros at impression time — {IMPRESSION_TRACKER}, {CLICK_TRACKER}, etc. — and substitutes buyer-supplied tracker URLs (declared on the manifest’s optional landing_page_url and the buyer’s measurement-vendor pixels declared via platform_extensions on the format, filtered by extensions[uri].extends === "tracking") into the rendered creative’s serving template. The buyer registers their measurement pixels client-side; the seller calls them at serve time. This is the dominant path for image / video / audio production where serving and tracking are decoupled.
• Sync-creatives tracker block. For products where the seller produces a serving artifact that embeds tracker URLs directly (e.g., a generated VAST tag or a stitched companion banner), the seller’s sync_creatives response SHOULD include a tracker_block field listing the impression URL pattern and click URL pattern. Buyers register those with their measurement vendor at sync time. This path covers the generative-DSP pattern where the serving artifact and the tracking shape are produced together.

​

What format_kind is NOT for

1. Creative type (image vs video vs audio vs html5 vs 3p-tag) → format_kind, the only knob it controls.
2. Production model (who renders, when) → asset_source on the format declaration.
3. Slot shape (what assets the buyer ships) → slots_override on the projection ref (catalog side) or on the v2 product’s format_options[] declaration.
4. Delivery medium / channel (TV vs streaming vs DOOH vs social) → applies_to_channels on the v2 product.
5. Measurement / tracking / event model. Splits two ways:
   • Renderer-fired trackers (the renderer hits a URL when serving / viewing / clicking) → pixel_tracker asset (or vast_tracker / daast_tracker on those formats). Lives on the creative manifest as a typed slot. Buyer’s measurement vendor URLs the seller’s renderer fires at serve time. See docs/creative/asset-types.mdx#pixel-tracker-asset.
   • Conversion pixels (fire on the advertiser’s site post-click — Meta Pixel, GA4 server-side, custom postbacks) → sync_event_sources / event_log. Campaign-scoped, NOT creative-asset-scoped. The same pixel fires for every ad in the campaign.
6. Targeting context (audience vs geo vs daypart) → media-buy targeting overlay, not the format.

​

When to use slots_override (and when to leave it off)

​

Custom formats — shapes the 12 canonicals don’t cover

​

The mechanism

{
  "format_options": [
    {
      "format_kind": "custom",
      "canonical_formats_only": true,
      "format_shape": "multi_placement_takeover",
      "format_schema": {
        "uri": "https://nytimes.example/schemas/formats/homepage_takeover_v3",
        "digest": "sha256:e1d4f6a9c2b5e8d1f4a7c0b3e6d9f2a5c8b1e4d7f0a3c6b9e2d5f8a1c4b7e0a3"
      },
      "capability_id": "nytimes_homepage_takeover_premium",
      "applies_to_channels": ["display", "olv"],
      "params": {
        "components": [
          { "placement_type": "homepage_skin", "required": true },
          { "placement_type": "preroll_video", "required": true },
          { "placement_type": "sponsorship_lockup", "required": true }
        ],
        "exclusivity_window_hours": 24
      }
    }
  ]
}

1. format_shape — recognized global pattern from the format-shape vocabulary registry. Tells buyer agents what kind of pattern they’re looking at (multi_placement_takeover, branded_content, ar_lens, etc.). The registry currently lists 9 shapes; non-canonical values are valid (validators MAY soft-warn) so adopters CAN ship a shape that isn’t yet in the registry — adding entries is a vocabulary PR, not a major-version bump.
2. format_schema — URI+digest reference to a fetchable schema describing the shape’s actual params and slots. Same hosting model as platform_extensions: open-ecosystem publishers host the artifact at the canonical URI on their subdomain; closed-platform / walled-garden shapes resolve through the AAO mirror at https://creative.adcontextprotocol.org/translated/.... Buyer agents fetch by uri@digest (immutable per digest, aggressive caching), validate params and slots against the fetched schema, and reason about manifests structurally.
3. params — the actual structure, governed by the schema fetched from format_schema.uri. AdCP doesn’t bake the params shape; the seller’s schema does.

​

format_schema fetch contract (normative)

• Transport: https:// only. http://, file://, data:, and other schemes MUST be rejected.
• SSRF protection: resolved hostname MUST NOT land on RFC 1918 (10/8, 172.16/12, 192.168/16), loopback (127/8, ::1), link-local (169.254/16, fe80::/10), CGNAT (100.64/10), or RFC 6761 special-use names (.local, .localhost, .internal, .test, .example, .invalid). Cloud metadata endpoints (169.254.169.254, metadata.google.internal, kubernetes.default.svc) are explicitly forbidden — these are credential-leak primitives. Connection MUST be pinned to the resolved IP (or re-resolved and re-validated per request) to defeat DNS rebinding.
• No redirects. HTTP redirects MUST be disabled on these fetches. Open redirects on same-origin paths are otherwise a free SSRF primitive.
• 1 MiB response cap. Enforce during streaming. Over-cap = hard fail.
• Digest mismatch is a hard fail. SHA-256 of the body MUST equal format_schema.digest (sha256: + 64 lowercase hex). On mismatch, the buyer MUST treat the declaration as unresolvable. No fallback to the unverified body. Sustained mismatch (vs network flap) MUST be distinguishable in telemetry — it’s a substitution-attack signal.
• Timeout ≤5s recommended. Timeout treated as a 5xx (transient — retry or skip).
• $ref sandboxing: fetched schemas MAY use $ref, but only to (a) same-origin URIs after RFC 3986 §6 normalization (lowercase scheme + host, strip default port, no userinfo), (b) the AAO catalog domain (https://creative.adcontextprotocol.org/...), or (c) intra-document JSON Pointer refs bounded to the parent document. Cross-origin $ref to arbitrary URIs MUST be rejected. $ref: file://... MUST be rejected. Transitive $ref depth ≤8 AND total $ref count ≤256 across the resolved tree (depth alone is not enough — depth 8 × breadth 100 = 10^16 nodes).
• Schema-compile bounds (DoS protection): validators MUST bound CPU/memory. Recommended: compiled-schema keyword count ≤10 000, pattern regexes evaluated with re2 OR under a per-pattern timeout, per-manifest validation budget ≤250 ms (exceeded → invalid + telemetry signal). Without these, a “valid” schema with catastrophic regex backtracking pins a CPU forever.
• Cache by uri@digest, immutable. On 404 / partition / persistent failure: skip the declaration for this session, surface via errors[], do NOT fail the whole get_products response.
• Schema validity: fetched body must be a valid JSON Schema (Draft 07 or 2020-12). Invalid schema → same as digest mismatch (unresolvable, surface via errors[], skip).
• AAO catalog domain: https://creative.adcontextprotocol.org/* is a single trust anchor in the allowlist; compromise of the catalog domain or its CA compromises every buyer agent. Catalog-served bodies are digest-pinned identically to origin fetches. Signed-body + transparency-log hardening is tracked as a 3.2 follow-up.

​

Why custom + format_schema instead of ext

​

Promotion to canonical

1. At least 2 production adopters ship it via custom + format_schema
2. 90 consecutive days without a breaking change to the shape adopters converged on
3. The shape has a defined tracking model (which signals fire, which trackers attach, what the impression contract is)
4. The working group opens a per-canonical promotion issue, drafts a canonical schema (/schemas/formats/canonical/<name>.json), lands a fixture, and ships in the next minor release

1. Transition window (≥90 days): sellers MAY emit both shapes simultaneously — format_options[] carrying one format_kind: "custom" + format_shape: "<name>" declaration AND one format_kind: "<promoted_name>" declaration.
2. Consumer-SDK deprecation warning: SDKs SHOULD emit a structured deprecation warning via their lint channel (same surface as FORMAT_PROJECTION_FAILED) when they see format_kind: "custom" with a format_shape that’s been promoted. Payload: { format_shape, promoted_to, promotion_release, transition_end }.
3. promotion_status lifecycle: the registry entry’s promotion_status updates from tracking — see adcp#3666 to promoted to <format_kind> in <version>; transition ends <date> when the working group schedules promotion. SDKs MAY read this at codegen / runtime.
4. Post-transition: sellers SHOULD drop the legacy format_kind: "custom" declaration. Buyers MAY then assume format_kind == "custom" is a long-tail / non-promoted shape.

​

Asset group vocabulary

​

Worked example — Meta Reels

​

Where each Reels feature lives

​

Where to declare a format

​

Format discovery (resolution order)

1. Publisher-hosted: fetch https://<publisher_domain>/.well-known/adagents.json. If present and carries formats[], return it. Response source: "publisher".
2. AAO community mirror: on 404 or absence-of-formats[], fall back to https://creative.adcontextprotocol.org/translated/<platform>/adagents.json. Return its formats[]. Response source: "aao_mirror".
3. Agent-derived: if neither tier returns a catalog, the agent synthesizes from the union of its own Product.format_options[] over products selling the publisher’s inventory. Response source: "agent_derived". Lowest authority — the agent’s view of what it sells, not the publisher’s catalog. Long-tail IAB publishers without a structured catalog will live here.

​

End-to-end fetch flow — buyer’s perspective

buyer holds: Product { publisher_properties: [{publisher_domain: "instagram.com"}],
                       format_options: [{capability_id: "meta_reels", ...}, ...] }
buyer wants: full ProductFormatDeclaration for each format_options entry,
             scoped to instagram.com's instagram property

• meta_reels → applies_to_property_ids: [“instagram”, “facebook”] → matches
• meta_feed_image → applies_to_property_ids: [“instagram”, “facebook”] → matches
• meta_stories_video → applies_to_property_ids: [“instagram”, “facebook”] → matches
• meta_feed_carousel → applies_to_property_ids: [“instagram”, “facebook”] → matches

GET https://instagram.com/.well-known/adagents.json
→ 404

GET https://creative.adcontextprotocol.org/translated/meta/adagents.json
→ 200 application/json
{
  "properties": [{"property_id": "instagram", ...}, ...],
  "formats": [
    { "capability_id": "meta_reels", "format_kind": "video_hosted",
      "applies_to_property_ids": ["instagram", "facebook"],
      "params": { ... } },
    ...
  ],
  "placements": [...]
}

(no superseded_by present — use as authoritative for unadopted platform)

filter formats[] by applies_to_property_ids ∋ "instagram":
→ 4 declarations match

product's format_options carries: [{ capability_id: "meta_reels" }]
→ resolve capability_id "meta_reels" against formats[] → full declaration

result: SDK knows the full ProductFormatDeclaration for the product,
        scoped to the right property, with the right v1 dual-emission
        format_ids[] from v1_format_ref[].

​

Community-registry hosting

// https://creative.adcontextprotocol.org/translated/meta/adagents.json (excerpt)
{
  "contact": { "name": "AdCP Community Registry — Meta translation", "domain": "adcontextprotocol.org" },
  "properties": [
    { "property_id": "instagram", "property_type": "mobile_app", "name": "Instagram", ... },
    { "property_id": "facebook",  "property_type": "mobile_app", "name": "Facebook",  ... },
    { "property_id": "whatsapp",  "property_type": "mobile_app", "name": "WhatsApp",  ... }
  ],
  "formats": [
    {
      "capability_id": "meta_reels",
      "display_name": "Meta Reels (Instagram + Facebook)",
      "format_kind": "video_hosted",
      "applies_to_property_ids": ["instagram", "facebook"],
      "v1_format_ref": [
        { "agent_url": "https://creative.adcontextprotocol.org/translated/meta", "id": "meta_reels" }
      ],
      "params": {
        "orientation": "vertical",
        "aspect_ratio": "9:16",
        "duration_ms_range": [3000, 90000],
        "min_width": 1080,
        "min_height": 1920,
        "video_codecs": ["h264"],
        "audio_codecs": ["aac"],
        "containers": ["mp4"],
        "headline_max_chars": 40,
        "primary_text_max_chars": 125,
        "cta_values": ["LEARN_MORE", "SHOP_NOW", "DOWNLOAD", "SIGN_UP", "CONTACT_US", "BOOK_NOW"],
        "composition_model": "deterministic"
      }
    }
  ],
  "placements": [
    {
      "placement_id": "instagram_reels",
      "name": "Instagram Reels",
      "property_ids": ["instagram"],
      "format_options": [{ "capability_id": "meta_reels" }]
    },
    {
      "placement_id": "facebook_reels",
      "name": "Facebook Reels",
      "property_ids": ["facebook"],
      "format_options": [{ "capability_id": "meta_reels" }]
    }
  ]
}

​

Product reuses the catalog declaration

{
  "product_id": "meta_reels_us",
  "name": "Meta Reels — United States",
  "publisher_properties": [
    { "publisher_domain": "meta.com", "selection_type": "all" }
  ],
  "channels": ["social"],
  "format_options": [
    {
      "format_kind": "video_hosted",
      "capability_id": "meta_reels",
      "v1_format_ref": [
        { "agent_url": "https://creative.adcontextprotocol.org/translated/meta", "id": "meta_reels" }
      ],
      "params": {
        "orientation": "vertical",
        "aspect_ratio": "9:16",
        "duration_ms_range": [3000, 90000],
        "min_width": 1080,
        "min_height": 1920,
        "video_codecs": ["h264"],
        "audio_codecs": ["aac"],
        "headline_max_chars": 40,
        "primary_text_max_chars": 125,
        "cta_values": ["LEARN_MORE", "SHOP_NOW", "DOWNLOAD", "SIGN_UP", "CONTACT_US", "BOOK_NOW"],
        "composition_model": "deterministic"
      }
    }
  ],
  "pricing_options": [
    { "pricing_option_id": "cpm_floor", "pricing_model": "cpm", "currency": "USD", "fixed_price": 5.50 }
  ]
}

​

What lives where (and why)

• Canonical params — fields the canonical already defines (dimensions, durations, codecs, CTA enum, char limits). Sellers narrow values; SDKs validate. Tight, codegen-clean.
• Canonical slots — content the manifest carries. video_hosted inherits video_main, headline, primary_text, cta, brand_name, companion_banner, landing_page_url. Products can override (remove slots the surface doesn’t use; mark required; narrow values).
• platform_extensions — net-new fields the canonical doesn’t recognize, scoped to one platform’s renderer (e.g., a hypothetical Reels music overlay carrying track_id + licensing flags). Bundled by URI+digest in get_products so buyers fetch once and cache.
• BrandRef + brand_kit_override — brand context (logo, colors, voice, tagline) consumed by formats whose seller-side renderer overlays brand. Host-read podcasts, CTV bumpers, publisher-direct display do consume it. Meta auto-overlays from the linked Page (auth context outside AdCP), so brand_kit_override has no effect for Meta Reels — it’s still the right schema location for the cases that DO consume it.
• Campaign / event-log surfaces — conversion tracking (Meta Pixel, GA4, server-side events). These belong on sync_event_sources / event_log (campaign-scoped, fires per impression regardless of creative). Format declarations carry creative shape; event-log declarations carry tracking configuration. Don’t put pixel_id in platform_extensions on a creative format.
• Media-buy surfaces — placement selection (Feed vs Reels vs Stories). Pick the right format on the publisher catalog (meta_reels vs meta_stories_video vs meta_feed_image); not a per-creative extension knob.

​

Worked example — IAB display (flexible multi-format, multi-size)

• format_kind is the creative TYPE — one of image, html5, display_tag, native, video_hosted — and never carries dimensional identity.
• Size lives in params as one of three modes (mutually exclusive):
  • Fixed: width + height integers — single accepted size (e.g., a 300×250-only legacy slot).
  • Multi-size: sizes: [{width, height}, ...] — list of accepted sizes for a flexible slot. Mirrors OpenRTB banner.format[].
  • Responsive: min_width/max_width + min_height/max_height — accepted dimensional ranges for slots that adapt to viewport.

{
  "product_id": "nytimes_homepage_flex_display",
  "name": "NYTimes.com Homepage Above-the-Fold Display",
  "publisher_properties": [
    { "publisher_domain": "nytimes.com", "selection_type": "all" }
  ],
  "channels": ["display"],
  "format_options": [
    {
      "format_kind": "image",
      "capability_id": "nytimes_homepage_image",
      "params": {
        "sizes": [
          { "width": 300, "height": 250 },
          { "width": 728, "height": 90 },
          { "width": 970, "height": 250 }
        ],
        "max_file_size_kb": 200,
        "image_formats": ["jpg", "png", "gif"],
        "ssl_required": true,
        "cta_values": ["LEARN_MORE", "SHOP_NOW", "GET_OFFER"]
      }
    },
    {
      "format_kind": "html5",
      "capability_id": "nytimes_homepage_html5",
      "params": {
        "sizes": [
          { "width": 300, "height": 250 },
          { "width": 728, "height": 90 },
          { "width": 970, "height": 250 }
        ],
        "max_initial_load_kb": 200,
        "max_polite_load_kb": 500,
        "backup_image_required": true,
        "om_sdk_required": true
      }
    },
    {
      "format_kind": "display_tag",
      "capability_id": "nytimes_homepage_3p_tag",
      "params": {
        "sizes": [
          { "width": 300, "height": 250 },
          { "width": 728, "height": 90 },
          { "width": 970, "height": 250 }
        ],
        "supported_tag_types": ["javascript", "iframe"],
        "ssl_required": true,
        "om_sdk_required": true
      }
    }
  ],
  "pricing_options": [
    { "pricing_option_id": "cpm_homepage", "pricing_model": "cpm", "currency": "USD", "fixed_price": 22.00 }
  ]
}

​

Worked example — Podcast 30s host-read

{
  "product_id": "the_daily_30s_host_read_us",
  "name": "The Daily — 30s Host-Read Pre-roll (US)",
  "publisher_properties": [
    { "publisher_domain": "thedailypod.example", "selection_type": "all" }
  ],
  "channels": ["podcast"],
  "format_options": [
    {
      "format_kind": "audio_hosted",
      "params": {
        "duration_ms_exact": 30000,
        "audio_codecs": ["mp3", "aac"],
        "audio_sample_rates": [44100, 48000],
        "audio_channels": ["stereo"],
        "loudness_lufs": -16,
        "asset_source": "publisher_host_recorded",
        "buyer_asset_acceptance": "rejected",
        "composition_model": "deterministic",
        "slots": [
          {
            "asset_group_id": "script",
            "required": true,
            "asset_type": "text",
            "max_chars": 800,
            "description": "Verbatim script the host reads."
          },
          {
            "asset_group_id": "offering_ref",
            "required": false,
            "asset_type": "text"
          }
        ],
        "production_window_business_days": 7
      }
    }
  ],
  "pricing_options": [
    { "pricing_option_id": "cpm_host_read", "pricing_model": "cpm", "currency": "USD", "fixed_price": 35.00 }
  ]
}

​

Flow 1 — buyer pre-produces (upstream creative agent)

1. Buyer reads The Daily’s product format → sees slots: [{ asset_group_id: "script", asset_type: "text", required: true }] declared
2. Buyer calls build_creative({ format: <The Daily's audio_hosted narrowing>, assets: { script: { asset_type: "text", content: "..." } }, brand: { domain: "..." } }) on a creative agent — this could be The Daily’s own creative-agent surface (if they expose one), or any other agent that declares it can produce this format via its creative.supported_formats on get_adcp_capabilities
3. Receives a rendered manifest with audio asset
4. Submits the rendered manifest via sync_creatives to The Daily’s sales agent

​

Flow 2 — seller produces internally

1. Buyer reads the same product format
2. Buyer submits via sync_creatives with the assets in the manifest (e.g., a script text asset under that slot in the assets map)
3. Seller produces internally; how is invisible to the buyer
4. Returns async status; buyer polls or waits for completion

​

Worked example — third-party creative agent (Flashtalking + NYTimes display)

• Buyer (Acme DSP) — discovers products, picks a creative agent (out-of-band: brand-side relationships, AAO registry, direct knowledge), submits manifests
• Sales agent (NYTimes) — sells the placement, validates manifests against the canonical its product narrows, doesn’t compose creatives, doesn’t maintain a list of “approved creative agents” in v2
• Creative agent (Flashtalking) — produces creatives via build_creative, declares its own producible catalog via creative.supported_formats on its OWN get_adcp_capabilities

​

1. Buyer reads NYTimes products

{
  "product_id": "nytimes_homepage_mrec",
  "format_options": [
    {
      "format_kind": "image",
      "params": { "width": 300, "height": 250, "max_file_size_kb": 200, "ssl_required": true }
    }
  ]
}

​

2. Buyer calls Flashtalking’s build_creative

// POST https://flashtalking.example/build_creative
{
  "format": {
    "format_kind": "image",
    "params": { "width": 300, "height": 250 }
  },
  "brand": { "domain": "acme.example" },
  "assets": {
    "creative_brief": { "asset_type": "brief", "content": "Spring sale, 50% off, blue background, urgent CTA." },
    "landing_page_url": { "asset_type": "url", "url": "https://acme.example/spring" }
  }
}

{
  "creative_id": "ft_mrec_88299",
  "manifest": {
    "format_id": { "agent_url": "https://flashtalking.example", "id": "image_300x250" },
    "assets": {
      "image": { "asset_type": "image", "url": "https://cdn.flashtalking.com/ft_mrec_88299.png", "width": 300, "height": 250 }
    }
  }
}

​

3. Buyer ships to NYTimes

1. Validates the manifest against canonical image (300×250, ≤200KB, SSL).
2. Validates against the product’s narrowing (matches — same params).
3. Does NOT validate against Flashtalking’s narrowing — that’s the creative agent’s contract with the buyer, not the seller’s contract.
4. If valid → creative registered. If not → returns canonical violations (width mismatch, max_file_size_kb exceeded).

​

Worked example — generative DSP (universalads-class, asset_source: seller_pre_rendered_from_brief)

{
  "product_id": "universalads_brief_driven_display_300x250",
  "name": "Universal Ads — Brief-Driven Display (300×250)",
  "publisher_properties": [
    { "publisher_domain": "universalads.example", "selection_type": "all" }
  ],
  "channels": ["display"],
  "format_options": [
    {
      "format_kind": "image",
      "params": {
        "width": 300,
        "height": 250,
        "max_file_size_kb": 200,
        "image_formats": ["jpg", "png"],
        "ssl_required": true,
        "composition_model": "deterministic",
        "asset_source": "seller_pre_rendered_from_brief",
        "buyer_asset_acceptance": "rejected",
        "production_window_business_days": 0,
        "slots": [
          { "asset_group_id": "creative_brief", "asset_type": "brief", "required": true, "max_chars": 500 },
          { "asset_group_id": "headline", "asset_type": "text", "required": true, "max_chars": 30 },
          { "asset_group_id": "landing_page_url", "asset_type": "url", "required": true }
        ]
      }
    }
  ],
  "delivery_type": "non_guaranteed",
  "pricing_options": [
    { "pricing_option_id": "cpm_brief", "pricing_model": "cpm", "currency": "USD", "floor_price": 8.00 }
  ]
}

​

Worked example — multi-format product (Flashtalking html5 OR internal display_tag)

{
  "product_id": "regional_news_homepage_300x250",
  "channels": ["display"],
  "format_options": [
    {
      "capability_id": "html5_flashtalking_hosted",
      "format_kind": "html5",
      "params": {
        "width": 300,
        "height": 250,
        "max_initial_load_kb": 200,
        "ssl_required": true,
        "composition_model": "deterministic"
      }
    },
    {
      "capability_id": "display_tag_internal",
      "format_kind": "display_tag",
      "params": {
        "width": 300,
        "height": 250,
        "ssl_required": true,
        "composition_model": "deterministic"
      }
    }
  ]
}

{
  "format_kind": "html5",
  "capability_id": "html5_flashtalking_hosted",
  "assets": { "html5_bundle": { /* ... */ }, "backup_image": { /* ... */ } }
}

• format_kind selects the canonical and its slot vocabulary.
• capability_id is REQUIRED on the manifest when the target product’s format_options contains two or more declarations sharing the same format_kind — without it, the seller can’t disambiguate which option the buyer is shipping against.
• capability_id is OPTIONAL when each format_kind in the product’s format_options is unique (the example above: one html5 entry, one display_tag entry) — format_kind alone routes the manifest. Buyers MAY still send capability_id as a clarity hint.

​

Worked example — sponsored_placement with item_production_model

{
  "product_id": "regional_retailer_generative_offerings",
  "channels": ["display"],
  "catalog_types": ["product"],
  "format_options": [
    {
      "format_kind": "sponsored_placement",
      "params": {
        "supported_catalog_types": ["product"],
        "min_items": 5,
        "max_items": 200,
        "fanout_mode": "per_item",
        "supported_id_types": ["sku", "gtin"],
        "item_production_model": "seller_pre_rendered_from_brief",
        "composition_model": "deterministic",
        "slots": [
          { "asset_group_id": "source_catalog", "asset_type": "catalog", "required": true },
          { "asset_group_id": "creative_brief", "asset_type": "brief", "required": true, "max_chars": 500 }
        ]
      }
    }
  ]
}

​

Worked example — Pinterest: which canonical?

​

Validation flow — validate_input

{
  "manifest": {
    "format_kind": "video_hosted",
    "assets": {
      "video_main": {
        "asset_type": "video",
        "url": "https://cdn.acme.example/spring-95s.mp4",
        "duration_ms": 95000,
        "width": 1080,
        "height": 1920
      }
    },
    "brand": { "domain": "acme.example" }
  },
  "targets": [
    { "kind": "canonical", "id": "video_hosted" },
    { "kind": "product", "id": "meta_reels_us" }
  ]
}

{
  "results": [
    {
      "target": { "kind": "canonical", "id": "video_hosted" },
      "result_kind": "validated_pass"
    },
    {
      "target": { "kind": "product", "id": "meta_reels_us" },
      "result_kind": "validated_fail",
      "violations": [
        {
          "rule": "duration_ms_range",
          "expected": "3000-90000",
          "predicted": 95000,
          "field": "assets.video_main.duration_ms"
        }
      ]
    }
  ]
}

​

When to use validate_input

• Pre-flight before an expensive build_creative call. If the manifest can’t even narrow against canonical, the buyer saves the synthesis cost. Especially relevant for nondeterministic-synthesis products where each retry has real GPU cost.
• Multi-target dry-run during product selection. A buyer comparing 10 candidate products asks validate_input once with all 10 product_ids; gets back per-target results. Cheaper than 10 separate sync_creatives round-trips.
• Debugging a rejected manifest. When sync_creatives returns violations, calling validate_input against the canonical alone narrows the question to “is my manifest fundamentally broken vs is the product’s narrowing the gating constraint.”
• Preview-render gating (formats with composition_model: algorithmic or synthesis_nondeterministic: true). The platform’s preview surface is a richer follow-on; validate_input is the cheap pre-flight that gates whether previewing is even worth attempting.

• For a manifest you intend to submit anyway. sync_creatives returns the same violations and registers on success — validate_input adds a round-trip without reducing total work.
• For products where the seller’s narrowing is unknowable client-side without fetching extensions. validate_input pulls extensions same as sync_creatives does — there’s no discovery shortcut.
• For high-volume per-impression decisions. validate_input is per-target, not per-impression. Operational scale (hundreds of products × N format_options) belongs to client-side filtering against the cached get_products response.

​

validate_input vs build_creative vs sync_creatives

​

Discovery + validation at scale

• Client-side filtering against the cached get_products response. Buyers who know their manifest’s format_kind and parameter bucket (canonical, dimensions, duration) filter the product list client-side before validating. The format declarations are already inline on each product — buyers don’t need a separate fetch to filter. This is the dominant pattern for “validate against the products that could possibly accept my creative” and reduces the validate_input set by an order of magnitude.
• Multi-target validate_input. When the filtered set is still wide (5-50 products), call validate_input once with all candidate product_ids in targets[]. The response carries per-target results in a single round-trip. Cheaper than per-product calls and structurally aligned with the schema (one request, many results).

​

Preview as the universal “what does this produce” surface

• Direct rendering: buyer ships finished creative assets (image, video, audio) → seller renders them on the placement → preview shows the rendered output (with seller-side composition, overlays, CTA buttons applied).
• Seller-side production: buyer ships content the seller consumes (script text, creative_brief, voice_id selection) → seller produces the rendered asset internally (host recording, generative AI synthesis, transcoding — invisible) → preview shows the produced output.

​

Brand identity via brand.json (with override)

{
  "format_kind": "image",
  "assets": {
    "image_main": { "asset_type": "image", "url": "https://cdn.acme.example/banner.jpg", "width": 300, "height": 250 }
  },
  "brand": {
    "domain": "acme.example",
    "brand_kit_override": {
      "logo": { "asset_type": "image", "url": "https://cdn.acme.example/logo-2026.png", "width": 200, "height": 100 },
      "colors": { "primary": "#0066CC", "accent": "#FF6600" },
      "tagline": "Spring savings, all season"
    }
  }
}

​

Platform extensions — distribution

https://creative.adcontextprotocol.org/translated/meta/extensions/meta_pixel
https://tiktok.example/extensions/tiktok_pixel
https://nytimes.example/extensions/nytimes_om_strict

{
  "products": [ { "...": "..." } ],
  "extensions": {
    "https://creative.adcontextprotocol.org/translated/meta/extensions/meta_pixel@sha256:a3f5...": {
      "extends": "tracking",
      "fields": {
        "pixel_id": { "type": "string", "required": true },
        "conversion_event": { "type": "string", "enum": ["PURCHASE", "LEAD"] }
      },
      "version": "2.1.0"
    }
  }
}

​

Dual emission and v2↔v1 projection (normative)

​

Producer rules

• SDKs that derive both shapes from a single source guarantee the invariant. Hand-authored products MUST be reviewed for agreement.
• A producer that cannot guarantee agreement MUST emit one shape only.
• For format_kind: "custom" declarations, producers MUST set canonical_formats_only: true and MUST NOT synthesize a v1 format_id. The protocol does NOT mint synthetic format_ids (an aao-synth/* namespace was considered and rejected — adopters would index on identifiers with no stable identity).
• For format_options declarations whose canonical/parameter shape has no clean v1 named-format equivalent (e.g., a structural shape not in v1-canonical-mapping.json and not declared on any v1 file), producers SHOULD set canonical_formats_only: true rather than emit only one of the two shapes silently.

​

Consumer rules (v1→v2)

1. Authoritative v2 → v1 link: if any v2 ProductFormatDeclaration on the same product carries v1_format_ref pointing at this v1 format_id, use that v2 declaration directly. Highest priority — seller asserts the link.
2. Seller-asserted on the v1 file: explicit canonical field on the v1 format declaration.
3. Registry glob: format_id_glob match.
4. Structural match: registry structural-shape match.
5. Fail closed: SDK MUST NOT synthesize a format_options entry. SDKs MUST augment the response’s errors[] array with an entry carrying source: "sdk", sdk_id, code: FORMAT_PROJECTION_FAILED, and the field+details (see error-code.json). Single mandated surface — lint-output channels are NOT acceptable; the multi-hop agent network needs warnings to propagate across SDK boundaries via the wire response. The advisory is non-fatal: the response stays 200/success, the product is still valid on the v1 path, only the v2 format_options projection is absent.

​

Consumer rules (divergence detection)

• SDKs MUST treat this as a producer contract violation.
• SDKs MUST prefer format_options (canonical formats are the richer surface) and MUST surface the divergent product via errors[] augmentation with source: "sdk", sdk_id, and code: FORMAT_DECLARATION_DIVERGENT. Single mandated surface — lint-output channels are not acceptable. Hard-failing the entire get_products response is discouraged — it punishes downstream buyers for a producer bug.
• SDKs MUST NOT silently pick one shape and discard the other without surfacing the divergence to the calling agent.

​

”Narrows” — formal definition (normative)

• Scalar constraints: a v2 scalar value narrows a v1 range when the v2 value is contained within the v1 range. v2.width: 300 narrows v1.width_range: [200, 400]; v2.duration_ms_exact: 30000 narrows v1.min_duration_ms: 3000.
• Enum constraints: v2.enum_value is a narrowing if it appears in v1.allowed_values (or v1.allowed_values is absent — open enum). v2.image_formats: ["jpg", "png"] narrows v1.image_formats: ["jpg", "png", "gif", "webp"].
• Range constraints: v2.range narrows v1.range when v2’s lower bound ≥ v1’s lower bound AND v2’s upper bound ≤ v1’s upper bound. v2.duration_ms_range: [5000, 30000] narrows v1.duration_ms_range: [3000, 90000].
• Absent v2 parameter: when v2.params omits a parameter that v1 specified, v2 inherits v1’s value (no narrowing constraint added). Producers SHOULD omit rather than restate v1 defaults.
• Asymmetric narrowing: when v1 says nothing about a parameter but v2 specifies one (e.g., v1 has no image_formats constraint, v2 declares image_formats: ["jpg"]), v2 is narrowing against the implicit “any value” v1 baseline. This is the expected v2-tightens-v1 pattern.
• Conflict: any v2 parameter value that falls outside the corresponding v1 constraint is a conflict, not narrowing. SDKs MUST treat conflict between dual-emitted shapes as divergence and surface via FORMAT_DECLARATION_DIVERGENT.

​

v1 → v2 projection via canonical: annotation (object shape)

"canonical": { "kind": "image" }

"canonical": {
  "kind": "image",
  "asset_source": "agent_synthesized",
  "slots_override": [
    { "asset_group_id": "generation_prompt", "asset_type": "text", "required": true }
  ]
}

1. kind → format_kind on the projected v2 ProductFormatDeclaration.
2. asset_source (if set) → params.asset_source. If absent, projection uses the canonical’s default (typically buyer_uploaded).
3. slots_override (if set) REPLACES the canonical’s default slots[] on the projected declaration. If absent, projection inherits the canonical’s defaults.
4. v1 entry’s requirements (dimensions, durations, codecs) → params fields per the canonical’s parameter schema.
5. v1 entry’s assets[*] MUST be consistent with the resulting slots[] — asset_id ↔ asset_group_id (asset-group-vocabulary resolves aliases).

​

v2 → v1 linking via v1_format_ref

​

Multi-size fan-out (normative)

• SDK does NOT fan out (default normative behavior). Emit format_ids[] carrying only the seller-asserted refs (size loss is real but bounded). MUST also emit FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE on the response errors[] with error.details: { product_id, declared_sizes, covered_sizes, dropped_sizes } so v1-aware downstream agents see what coverage was lost. The lossy emit is the conservative wire shape — exactly what the seller asserted, no synthesis.
• SDK DOES fan out (MAY-do, non-normative). For each entry in sizes[] lacking a corresponding v1_format_ref, the SDK MAY consult the AAO catalog and look up the per-size v1 named format (e.g., for {width: 728, height: 90} → display_728x90_image). When the lookup succeeds, the SDK MAY emit the catalog-resolved ref under format_ids[] alongside the seller-asserted refs. SDKs that fan out MUST still emit FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE as a transparency advisory so downstream consumers know which format_ids[] entries were seller-asserted vs catalog-resolved. The advisory’s error.details SHOULD include synthesized_refs: [<list of catalog-resolved ids>].

{
  "format_kind": "custom",
  "format_shape": "multi_placement_takeover",
  "format_schema": { "uri": "https://nytimes.example/schemas/formats/homepage_takeover_v3", "digest": "sha256:..." },
  "v1_format_ref": [{ "agent_url": "https://nytimes.example", "id": "homepage_takeover" }],
  "params": { ... }
}

​

v2-only declarations on the wire

​

v2-native sellers emitting to v1 buyers

1. Default — set canonical_formats_only: true, omit from format_ids. v1 buyers see no format_ids entry for these declarations. The product is functionally invisible to v1-only buyers, but the v1 surface stays clean (no synthetic identifiers polluting buyer-side allowlists).
2. Synthesize seller-scoped IDs. When a seller wants v1-only buyer reach, they MAY mint format_ids like <seller_domain>/canonical_<format_kind>_<param_summary> (e.g., acme.example/canonical_image_300x250). When synthesizing:
   • The IDs MUST be seller-scoped (under the seller’s own agent_url), never under aao-synth/* or any cross-seller namespace — the AAO-mirror-style synthetic namespace was considered and rejected because adopters would index on identifiers with no stable identity.
   • The IDs MUST be declared in the seller’s published format catalog (the static format file referenced by their adcp-resource manifest, the same place list_creative_formats reads from) so v1 buyers see consistent identifiers between Product.format_ids and the seller’s format directory.
   • The format_kind_<param_summary> convention is a recommendation, not a normative requirement — sellers MAY use any naming convention scoped to their own agent_url namespace. Buyers MUST NOT pattern-match on the convention for routing (the seller’s catalog is authoritative).
   • The synthetic format_ids entry and the corresponding format_options entry MUST satisfy the same dual-emission narrowing contract as any other dual-emitted product (see the projection rules above).

​

What’s NOT in v2

• Brand safety vocabularies — that’s media-buy/campaign-level (creative-policy.json and broader campaign settings), not creative-format-level. Format declarations don’t redeclare brand safety.
• Universal macros as a new schema — already documented at /docs/creative/universal-macros. Canonical formats reference them by name.
• destination_kinds as a new schema — url-asset.json already has url_type covering URL kind disambiguation. Platform-specific destinations (Meta messenger_thread, etc.) are platform extensions.
• cta_vocabulary as a canonical pattern — CTAs vary meaningfully across surfaces; we let products declare cta_values arrays inline until cross-platform demand emerges.
• list_build_capabilities as a separate tool — folded into get_adcp_capabilities under creative.supported_formats.
• build_capability, build_capability_ref, and a separate inputs map — collapsed into the canonical slots model on the format declaration. The format declares slots (canonical asset_group_id + asset_type + constraints); the manifest has a single assets map keyed by slot name; the seller dispatches per the format (render assets verbatim or consume them for production). The format itself tells the buyer what it requires; how production happens is implementation detail.

​

Channels covered by sibling refinement (no new canonical)

• Linear / addressable TV — video_hosted + applies_to_channels: ["tv"]. Asset is still a video file with size/codec/duration constraints. The GRP/spot transaction model and addressable household targeting are media-buy + measurement concerns, not creative-format concerns.
• OOH / DOOH — image (or video_hosted) + applies_to_channels: ["dooh"]. Asset is still a still image (or short video) with size constraints. Location-keyed measurement (Geopath, COMMB) belongs on sync_event_sources / event_log, not on the format.
• Generative-from-prompt — same format_kind as the buyer-uploaded equivalent (image, video_hosted, audio_hosted) + asset_source: agent_synthesized + slots_override declaring the input shape (generation_prompt: text, creative_brief: brief, video_brief: object). v2-aware buyers see “this format wants a text prompt or structured brief, not image bytes.”
• Video native — video_hosted + applies_to_channels: ["native"]. The asset is still a hosted video file; the difference is renderer placement (in-feed) and is captured by the channel axis. (For non-video in-feed native units — title + image + body assembled by the renderer — use the dedicated native_in_feed canonical, which has a meaningfully different assembly shape.)

• Audio dynamic ad insertion (DAI) — ad-stitched audio with mid-stream insertion has a different tracking shape than audio_hosted or audio_daast. Likely a specialized canonical or audio_daast extension parameters when the pattern stabilizes.
• In-game — playable / in-game ads have a SDK-specific composition model. Out of scope until cross-engine standards land.
• Live streaming — live linear video (Twitch / YouTube Live / sports streaming with mid-roll) needs concurrent-impression and stream-state tracking. The video_vast canonical handles VAST-tag-driven live insertion today; richer live patterns deferred.

​

Generative-DSP and multi-output patterns are forward-looking

​

Creative-agent business model

​

Codegen vs runtime: the validator is the gate

• Generated TS / Python types accept a format_kind: "custom" declaration that omits format_shape or format_schema — the type system has no way to narrow on the discriminator and require the conditional fields.
• The Ajv (or equivalent) runtime validator IS the gate. SDKs MUST run the JSON Schema validator before trusting a ProductFormatDeclaration parsed from the wire; the codegenned type is a convenience layer, not a contract.
• Buyer-agent authors writing v2 in TypeScript SHOULD treat the generated types as a starting point and add their own runtime validation step — same pattern adopters already use for any JSON-Schema-validated API. Adopters who skip runtime validation will get type-system success on declarations that the schema rejects, and discover the gap only when their declarations hit a strict downstream validator.

​

Migration

​

Realistic 3.1 coverage

​

Phase status

​

Empirical projection coverage

• 8 generative entries (display_generative, display_300x250_generative, display_728x90_generative, display_320x50_generative, display_160x600_generative, display_336x280_generative, display_300x600_generative, display_970x250_generative) — annotated as { kind: "image", asset_source: "agent_synthesized", slots_override: [{ generation_prompt: text, required }] }. v2-aware buyers projecting see “this format wants a text prompt, not image bytes.” Sibling refinement on asset_source + slots_override; no image_generative canonical needed.
• 3 broadcast (broadcast_spot_15s/30s/60s) — { kind: "video_hosted" }. Sellers narrow via applies_to_channels: ["tv"] on the v2 product. Same asset shape (video file + duration + codec).
• 4 DOOH (dooh_billboard_*, dooh_transit_screen) — { kind: "image" }. Sellers narrow via applies_to_channels: ["dooh"]. Location-keyed measurement differences live on sync_event_sources, not on the format.
• 2 native (native_standard, native_content) — { kind: "image", asset_source: "buyer_uploaded", slots_override: [...] } with native-specific slots (icon, disclosure, sponsored_by).

​

Related

• v1 → canonical-formats migration guide — concrete migration paths for sellers, creative agents, buyers, and publisher-direct integrations
• RFC #3305 — v2 architecture decisions and rationale
• PR #3307 — Phase 1 + Phase 2 implementation, on hold pending 3.1.0 beta cycle
• Asset group vocabulary — canonical slot-name registry
• Video Brief schema — typed per-segment generation brief for build_creative (renamed from earlier scenes)
• Universal macros — substitution patterns referenced from canonical tracking