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.

​

Migration: v1 named formats → Canonical Formats

Naming note: The v1↔v2 terminology used throughout this page describes the two format-authoring models — format_ids (legacy, v1) vs format_options (canonical formats, v2). It does NOT refer to AdCP-the-protocol’s version (currently 3.x). The “v2” path is also called the canonical-formats path; both phrasings mean the same thing.

​

What stays unchanged

• All asset primitive schemas (image-asset.json, video-asset.json, audio-asset.json, vast-asset.json, daast-asset.json) — unchanged
• Catalog and offering schemas — unchanged
• Manifest envelope shape (creative-manifest.json keyed by assets map) — unchanged
• Response envelopes, error schemas, common types — unchanged
• v1 named formats (format.json with compound format_id) — still supported through 4.x
• v1 list_creative_formats tool — deprecated but functional through 4.x; removed at 5.0
• All existing producers and consumers — continue to work without changes

​

Side-by-side: a v1 named format → v2 product format declaration

​

v1 — separate format file referenced by product

// formats/meta_reels.json
{
  "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "meta_reels" },
  "name": "Meta Reels",
  "type": "video",
  "assets": [
    {
      "asset_id": "video_file",
      "asset_type": "video",
      "asset_role": "hero_video",
      "item_type": "individual",
      "required": true,
      "requirements": {
        "min_duration_ms": 3000,
        "max_duration_ms": 90000,
        "aspect_ratio": "9:16",
        "min_width": 1080,
        "min_height": 1920,
        "containers": ["mp4"],
        "codecs": ["h264"]
      }
    }
  ]
}

// products/meta_reels_us.json
{
  "product_id": "meta_reels_us",
  "name": "Meta Reels — United States",
  "format_ids": [
    { "agent_url": "https://creative.adcontextprotocol.org", "id": "meta_reels" }
  ],
  // ... pricing, targeting, etc.
}

​

v2 — inline format declarations on the product

{
  "product_id": "meta_reels_us",
  "name": "Meta Reels — United States",
  "format_options": [
    {
      "format_kind": "video_hosted",
      "params": {
        "orientation": "vertical",
        "aspect_ratio": "9:16",
        "duration_ms_range": [3000, 90000],
        "min_width": 1080,
        "min_height": 1920,
        "video_codecs": ["h264"],
        "containers": ["mp4"],
        "headline_max_chars": 25,
        "primary_text_max_chars": 72,
        "cta_values": ["LEARN_MORE", "SHOP_NOW", "DOWNLOAD", "SIGN_UP"],
        "composition_model": "deterministic",
        "platform_extensions": [
          { "uri": "https://creative.adcontextprotocol.org/translated/meta/extensions/meta_pixel", "digest": "sha256:..." }
        ]
      }
    }
  ],
  // ... pricing, targeting, etc.
}

​

v1 → v2 canonical mapping

​

The canonical mapping registry

• format_id_glob — exact / glob match against v1 format_id.id. Covers IAB-conventional sizes (iab/mrec_300x250 → image 300×250), named platform formats, common publisher conventions.
• structural — match against the format’s slot shape, asset types, and version constraints. Catches custom v1 formats that are structurally a standard format under a different name (a seller’s acme_homepage_300x250 is structurally an IAB MREC).

​

canonical field on v1 format declarations (custom / non-registered formats)

{
  "format_id": "acme/sponsored_recipe_card",
  "name": "Sponsored Recipe Card",
  "canonical": { "kind": "sponsored_placement" },
  "canonical_parameters": {
    "format_kind": "sponsored_placement",
    "params": {
      "supported_catalog_types": ["product"],
      "supported_id_types": ["sku"],
      "fanout_mode": "per_item",
      "item_production_model": "buyer_uploaded"
    }
  },
  "assets": [
    { "asset_id": "headline", "asset_type": "text", "asset_group_id": "headline", "required": true },
    { "asset_id": "recipe_image", "asset_type": "image", "asset_group_id": "image_main", "required": true }
  ]
}

​

Normative SDK projection rules

1. If the v1 format declaration carries canonical, use it (seller-declared, highest priority). When canonical_parameters is also present, use that as the projected ProductFormatDeclaration verbatim.
2. Else, look up format_id in /schemas/registries/v1-canonical-mapping.json’s format_id_glob entries.
3. Else, attempt structural match against the registry’s structural entries.
4. Else, fail closed: SDK MUST NOT emit format_options for products carrying this format. Surface a validation warning suggesting the seller add an explicit canonical field or file a registry entry. Buyers see format_ids only for these products.

​

Slot name mapping (v1 → canonical)

// v1 format with author-invented slot name
{
  "asset_id": "click_url",
  "asset_type": "url",
  "item_type": "individual",
  "required": true
}

// Same v1 format with canonical pointer (additive — backwards-compatible)
{
  "asset_id": "click_url",
  "asset_type": "url",
  "asset_group_id": "landing_page_url",
  "item_type": "individual",
  "required": true
}

​

Discovery surface migration

​

Generative formats — *_generated_* files dissolve

• The format declaration’s slots array enumerates everything the buyer ships in the manifest’s assets map — each entry is a canonical asset_group_id paired with an asset_type. Some slots are rendered verbatim (image / video / audio); some are consumed for production (text script → host-read audio; brief → synthesized image; video_brief → generated video). The seller dispatches per slot.
• Whether the seller’s internal production is generative AI, host recording, transcoding, or asset rendering is invisible to the buyer
• A single canonical format (e.g., audio_hosted) handles both buyer-uploaded audio and agent-produced audio; the format’s asset_source and buyer_asset_acceptance parameters describe which flows are accepted

// v1: separate generated format file
{
  "format_id": { "agent_url": "...", "id": "audiostack_audio_30s_generated" },
  "name": "AudioStack 30s Audio (Generated)",
  "assets": [
    {
      "asset_id": "creative_brief",
      "asset_type": "brief",
      "required": true
    },
    {
      "asset_id": "audio_output",
      "asset_type": "audio",
      "required": false
    }
  ]
}

// v2: same canonical (audio_hosted), buyer-shipped assets declared as slots
{
  "format_kind": "audio_hosted",
  "params": {
    "duration_ms_exact": 30000,
    "audio_codecs": ["mp3"],
    "loudness_lufs": -16,
    "asset_source": "agent_synthesized",
    "buyer_asset_acceptance": "rejected",
    "slots": [
      { "asset_group_id": "creative_brief", "required": true, "asset_type": "brief", "max_chars": 1000 },
      { "asset_group_id": "voice_id", "required": false, "asset_type": "text" }
    ],
    "production_window_business_days": 0
  }
}

​

Brand identity — slots disappear

{
  "format_id": { "agent_url": "...", "id": "..." },
  "assets": { ... },
  "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"
    }
  }
}

​

Tools — what’s new vs unchanged

​

Adopter migration paths

​

Sales agents (DSPs, SSPs, retail media networks, walled gardens)

1. Inventory: enumerate your existing v1 named formats. Confirm each maps to one of the 12 v2 canonicals OR to a custom shape (see “Shipping a custom format” below). Composed/coordinated/sponsorship shapes (multi-placement takeover, roadblock, branded content, cross-screen sponsorship, sponsorship lockup, newsletter, AR lens, playable, live event sponsorship) ship as format_kind: "custom" with a format_shape registry classifier and a format_schema URI+digest reference.
2. Translate: for each named format, write a v2 ProductFormatDeclaration narrowing the canonical with your platform’s parameters. For custom shapes, author a JSON Schema describing your format’s params and slots, host it at a stable URI on your subdomain (or via the AAO mirror for walled-garden sellers), and reference it from format_schema.
3. Be honest about runtime readiness: set experimental: true on each declaration whose runtime path isn’t fully wired yet. Same flag whether the concern is “spec is still settling” (canonical-level) or “my runtime is mid-migration” (declaration-level). Buyers SHOULD filter experimental: true from default views; they SHOULD prefer the v1 fallback (via the declaration’s v1_format_ref or the parent product’s format_ids) until you drop the flag. Drop the flag when the runtime catches up.
4. Test: validate translated declarations against /schemas/core/product.json (use the npm run test:canonical-fixtures pattern).
5. Publish dual: keep your v1 named formats and list_creative_formats working through 4.x. Add the v2 format_options field on products that have it.
6. Flatten wrapper: implement a server-side wrapper that derives the v1 list_creative_formats shape from v2 product declarations. Lets v1-era dashboards and tooling keep working.
7. Deprecate timing: at 5.0, remove v1 format_ids references on your products. Until then, both paths coexist.

​

Server-side implementation considerations

• sync_creatives provenance verification when provenance_required: true. When a v2 product’s format declaration carries provenance_required: true (and the buyer’s manifest contains synthesized assets — typically video/image from generative platforms), sync_creatives MUST verify a C2PA-compatible provenance manifest is attached and reject unsigned synthesized assets. This is a natural extension of existing AI-provenance tracking on Creative (EU AI Act Article 50 work) — the new piece is a validation hook that gates submission. Sellers without existing provenance plumbing only need this once they ship a v2 product with the flag set; until then it’s no-op.
• get_products response gathers extension definitions. When products carry v2 format.params.platform_extensions references, the response SHOULD include the referenced extension definitions in the extensions map keyed by <uri>@sha256:<digest>. Implementations gather extensions referenced by any product in the response, dedupe by digest, and emit. Buyers cache by URI@digest; subsequent responses MAY omit definitions the buyer already has cached. Trivial when no products use v2 declarations; only kicks in when tenants opt in.
• production_window_business_days on host-read / agent-produced products. Today most server implementations don’t model production turnaround on Products — the field is a v2 addition. Only matters once a tenant ships a v2 host-read or generative-video product (audio_hosted with asset_source: 'publisher_host_recorded', or any product with synthesis_nondeterministic: true). Today many of these flows route through hand-trafficked sponsorships and don’t surface turnaround over the protocol; v2 makes it declarable.

​

Shipping a custom format

1. Pick a format_shape from the vocabulary registry. If your shape isn’t there, file a vocabulary PR — adding entries is governance-light, doesn’t require a major version bump, and helps the working group track adoption velocity per shape.
2. Author a JSON Schema describing your format’s params and slots. The schema’s job is to give buyer agents enough structure to validate manifests and reason about what assets you accept, how you track, what the impression contract is. Treat it like authoring a v1 named format file — same level of rigor, just hosted at your URI rather than under AdCP’s roof. Industry-shared schemas (e.g., a shared multi_placement_takeover_v1 schema several publishers converge on) are encouraged and accelerate canonical promotion.
3. Host the schema at a stable URI with Cache-Control: public, max-age=31536000, immutable and a digest. Open-ecosystem publishers host on their own subdomain (https://yourpub.example/schemas/formats/your_shape_v1); walled-garden sellers route through the AAO mirror at https://creative.adcontextprotocol.org/translated/<vendor>/<shape> (AAO accepts translation submissions; same hosting / immutability contract). Reference the schema from format_schema: { uri, digest } on your ProductFormatDeclaration.

​

Creative agents (Flashtalking, AudioStack, generative platforms, AI rendering services)

​

What changes for a creative agent in v2

​

Concrete example: Flashtalking-shaped creative agent

// GET https://flashtalking.example/.well-known/agent.json
// → get_adcp_capabilities response (excerpt)
{
  "creative": {
    "supports_generation": true,
    "supports_transformation": true,
    "has_creative_library": true,
    "supported_formats": [
      {
        "capability_id": "flashtalking_image_iab_standard",
        "format": {
          "format_kind": "image",
          "params": {
            "image_formats": ["jpg", "png", "gif"],
            "max_file_size_kb": 200,
            "ssl_required": true,
            "asset_source": "buyer_uploaded",
            "platform_extensions": [
              { "uri": "https://flashtalking.example/extensions/flashtalking_pixel_v2", "digest": "sha256:..." }
            ]
          }
        }
      },
      {
        "capability_id": "flashtalking_video_vast_42",
        "format": {
          "format_kind": "video_vast",
          "params": {
            "vast_version": "4.2",
            "duration_ms_range": [6000, 60000],
            "linear_required": true,
            "ssl_required": true,
            "platform_extensions": [
              { "uri": "https://flashtalking.example/extensions/flashtalking_vpaid_2_0", "digest": "sha256:..." }
            ]
          }
        }
      },
      {
        "capability_id": "flashtalking_html5_iab_standard",
        "format": {
          "format_kind": "html5",
          "params": {
            "max_initial_load_kb": 200,
            "om_sdk_required": true,
            "backup_image_required": true,
            "ssl_required": true
          }
        }
      }
    ]
  }
}

​

Concrete example: AudioStack-shaped transformation agent

// GET https://audiostack.example/.well-known/agent.json
{
  "creative": {
    "supports_generation": true,
    "supports_transformation": true,
    "supported_formats": [
      {
        "capability_id": "audiostack_audio_brief_to_30s",
        "format": {
          "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": "seller_pre_rendered_from_brief",
            "buyer_asset_acceptance": "rejected",
            "production_window_business_days": 1,
            "slots": [
              { "asset_group_id": "creative_brief", "asset_type": "brief", "required": true, "max_chars": 500 },
              { "asset_group_id": "voice_id", "asset_type": "text", "required": false },
              { "asset_group_id": "landing_page_url", "asset_type": "url", "required": false }
            ]
          }
        }
      },
      {
        "capability_id": "audiostack_audio_script_to_30s",
        "format": {
          "format_kind": "audio_hosted",
          "params": {
            "duration_ms_exact": 30000,
            "audio_codecs": ["mp3"],
            "asset_source": "agent_synthesized",
            "buyer_asset_acceptance": "rejected",
            "synthesis_nondeterministic": false,
            "production_window_business_days": 0,
            "slots": [
              { "asset_group_id": "script", "asset_type": "text", "required": true, "max_chars": 800 },
              { "asset_group_id": "voice_id", "asset_type": "text", "required": true }
            ]
          }
        }
      }
    ]
  }
}

​

Server-side hooks for creative agents

• creative.supported_formats is your public contract. Buyers and sales agents read it to know what you produce. Keep capability_id values stable across releases — buyers reference them in their build_creative calls.
• synthesis_nondeterministic: true implies a QA-loop obligation. When you declare it, you commit to: validating each synthesis attempt against the format’s parameter constraints; reseeding up to N times to produce in-spec output; returning task_failed with synthesis_failed reason if the loop exhausts. There is no protocol state for orphaned out-of-spec artifacts — the buyer never sees a partial result.
• provenance_required: true requires C2PA attestation. When a sales agent’s product carries provenance_required: true and the buyer is shipping your produced asset, the manifest you return MUST include a C2PA-compatible provenance manifest attributing synthesis to your agent (not the buyer, not the seller). EU AI Act Article 50 alignment.

​

Migration timing for creative agents

​

Buyers / DSPs

1. Update your client to read either format_ids (v1) or format (v2 inline) on products.
2. Use validate_input for cheap dry-run validation before committing to renders.
3. Use the canonical asset_group_id vocabulary when constructing manifests; the registry’s aliases field maps v1-era slot names to canonical equivalents.
4. Submit creative via sync_creatives as before. For products whose slots accept production content (host-read podcasts ship a script text asset; generative video ships a creative_brief and video_brief), either pre-produce via a creative agent’s build_creative to get back a manifest with rendered assets OR submit the production-content assets directly and let the seller produce internally — both flows are valid.

​

Publisher direct (GAM/prebid path)

1. The zip asset type (Phase 1) handles HTML5 banner bundles cleanly. URL-delivered HTML/JS routes through url-asset.json with appropriate url_type.
2. Tag-based delivery (VAST, third-party display tags) maps to the display_tag, video_vast, and audio_daast canonical formats.
3. Native canonical format is deferred to 3.2 after the TemplateCreative + OpenRTB Native 1.2 audit; until then, native formats stay on the v1 path.

​

Realistic timeline by adopter type

​

When does v1 format_ids get removed?

• Floor (minimum end-of-life): v1 format_ids is supported through at least 2027-Q4 regardless of adoption signal. Adopters whose org reality (legacy ad-server integrations, walled-garden translation gaps, slow procurement cycles) prevents immediate migration get an unconditional 18-month runway from 3.1 GA.
• Ceiling (maximum end-of-life): v1 format_ids is removed no later than 2029-Q1 regardless of adoption signal. Caps the long-tail liability for SDK authors and validator maintainers; matches the v2-sunset-policy pattern from 3.0.
• Adoption trigger (within the floor / ceiling window): AAO computes the ratio of registered sales agents declaring format_options (vs format_ids) from cached get_products capabilities responses. The trigger is denominator = sales agents declaring creative in supported_protocols; numerator = those whose latest get_products response carries format_options on every product. When the ratio crosses 80% and stays there for 30 consecutive days within the floor/ceiling window, the 5.0 cut sequence opens (deprecation warnings escalate; the next major drops format_ids). Until that signal trips, both shapes remain valid.

​

creative_id stability across v1 ↔ v2

​

product_card and product_card_detailed are typed inline

"product_card": {
  "image": { "asset_type": "image", "url": "https://...", "width": 300, "height": 400 },
  "title": "Meta Reels — United States",
  "description": "9:16 vertical short-form video on Meta Reels.",
  "price_label": "From $5.50 CPM",
  "cta_label": "View details"
}

"product_card_detailed": {
  "hero_image": { "asset_type": "image", "url": "...", "width": 1200, "height": 600 },
  "carousel_images": [ { "asset_type": "image", "url": "...", ... }, ... ],
  "title": "Meta Reels — United States",
  "description": "Full markdown-friendly product description...",
  "specifications": [
    { "label": "Aspect ratio", "value": "9:16" },
    { "label": "Duration", "value": "3-90s" }
  ],
  "price_label": "From $5.50 CPM",
  "cta_label": "Get proposal"
}

​

What v2 gives you that OpenRTB doesn’t

• Buyer validates against the canonical, not the seller’s narrowing. OpenRTB has no canonical layer. Each SSP authors its own native asset spec (Native 1.2 left placement-specific assets to “see the impl”); each video player authors its own VAST extensions; each retail-media network publishes its own catalog field shape. Buyers must discover and validate against per-seller specs at runtime. v2’s canonical-as-contract decouples buyer validation from per-seller schema discovery — the buyer ships a manifest that satisfies canonical image and knows it’s structurally valid against any seller speaking that canonical, BEFORE knowing which seller wins the auction.
• Discovery is operational, not implicit. OpenRTB Display 1.x and Native 1.2 expect adopters to read the spec, write per-version handlers, and pre-bake support for what each seller might require. v2 carries the format declaration inline on the product (format_options[i] on get_products) and on the creative agent (creative.supported_formats on get_adcp_capabilities). Buyers fetch what’s accepted at runtime; SDK codegen produces typed handlers for the canonicals; new sellers don’t require buyer-side code changes.
• Production source is first-class. OpenRTB has no notion of “buyer ships a brief; seller renders.” The closest expression is OpenRTB Native’s nobid_reason after submission. v2 makes production source a declared parameter (*_source enums), so generative DSPs and host-read products are visible at discovery time, not only after rejection.
• Tracking model is canonical-defined. OpenRTB tracking (impression NURL, click NURL, third-party trackers) is consistent for VAST but fragmented for native and display. v2 bakes the tracking model into each canonical (impression pixel for image, MRAID + OM-SDK for html5, VAST events for video_vast, per-card pixels for image_carousel) — buyers know what tracking shape applies from the canonical alone.

​

Validating your migration

npm run test:canonical-fixtures

​

Related

• Canonical Formats overview
• RFC #3305 — architectural decisions and rationale
• Asset group vocabulary
• BrandRef schema
• Universal macros — substitution patterns referenced from canonical tracking