RFC #3305 implementation preview — v2 creative formats (full spec, not for merge)

[bokelley]

Status: Preview branch implementing RFC #3305 end-to-end. Not for merge until the 3.1.0 beta cycle opens — merging earlier would force a 3.1.0 release before the rest of v2 work is ready. Adopters and upstream implementors can check this branch out and build against the v2 spec.

Scope: Phase 1 (foundational primitives) + Phase 2 (canonical format catalog, product format declarations, validate_input tool, supporting schemas) + Phase 3 (migration guide, reference fixtures, fixture-validation test). Backwards-compatible additions only — no v1 producers or consumers are affected.

Read this first

• RFC #3305 — architectural decisions and rationale (currently at r4)
• docs/creative/v2-overview.mdx — adopter-facing walkthrough with Meta Reels, IAB MREC + sibling HTML5, podcast host-read, and Amazon SP worked examples
• docs/creative/v2-migration.mdx — concrete v1 → v2 migration paths per adopter type

Validate against the spec yourself

Five fully-valid reference Product fixtures at static/examples/products/v2/ pass strict schema validation:

npm run test:v2-fixtures

Fixtures:

• meta_reels_us.json — video_hosted (vertical), Meta-specific extensions
• nytimes_homepage_mrec.json — image (IAB MREC 300×250)
• nytimes_homepage_html5.json — html5 (sibling product, different canonical because different tracking model)
• the_daily_30s_host_read.json — audio_hosted with inline inputs (script + brand)
• amazon_sponsored_products.json — sponsored_placement (catalog-driven, ASIN-keyed)

What landed in this PR

Foundations (Phase 1)

• asset-group-vocabulary.json — canonical asset_group_id registry (7 existing catalog entries + 12 audit-driven additions). Aliases expanded for headlines, descriptions, images_*, logo, video, audio. Canonicalizes landing_page_url over 6 v1 alias names.
• scenes.json — typed scene-by-scene structure for generative video inputs.
• zip-asset.json — first-class asset type for HTML5 banner bundles.
• Doc fixes at docs/creative/channels/{video,audio}.mdx correcting VAST asset_type.

Canonical format catalog (Phase 2)

11 canonical format definitions at static/schemas/source/formats/canonical/:

Canonical	What it is	Tracking
image	Static image	Impression pixel + click URL
html5	Interactive HTML5 banner (zip asset)	MRAID + OM-SDK + click-tag macro + backup image
display_tag	Third-party JS/iframe tag	Opaque to seller
image_carousel	Multi-card swipe (polymorphic items)	Per-card pixels + carousel engagement
video_hosted	Direct video file (orientation parameter)	OM-SDK + external trackers
video_vast	VAST tag	Inherent VAST events
audio_hosted	Direct audio (or host-read produced via build_creative)	Standard impression/completion
audio_daast	DAAST tag	Inherent DAAST events
sponsored_placement	Retail-media catalog-driven (Amazon SP, Criteo SP, CitrusAd SP)	Per-item catalog-keyed
responsive_creative	Buyer asset pool, surface composes (Google RDA/RSA/PMax/Demand Gen, Meta Advantage+)	Per-asset performance
agent_placement	AI-surface composed sponsored placement (ChatGPT, Perplexity, voice assistants). Distinct from si_chat.	Mention-level impression + attribution

Each canonical bakes in its tracking model. Format-keyed-by-name structure (no canonical discriminator field). _base.json defines shared parameters: composition_model, provenance_required, platform_extensions, tracking_extensions, inputs, production_window_business_days.

Product/manifest declarations (Phase 2)

• product-format-declaration.json — keyed by canonical format name, exactly one key per declaration
• product.json — adds optional format field (v2 inline declaration); oneOf enforces v1 (format_ids) XOR v2 (format)
• creative-manifest.json — adds optional brand (using canonical BrandRef) and brand_kit_override
• format.json slot declarations — gain optional asset_group_id field (v1↔v2 migration bridge)

Tools (Phase 2)

• validate-input-{request,response,result}.json — buyer dry-run primitive
• creative.supported_formats field added to get_adcp_capabilities response — uniform replacement for list_creative_formats regardless of agent role
• platform-extension-ref.json — URI + content-digest reference for platform extensions

Adopter docs (Phase 2 + Phase 3)

• docs/creative/v2-overview.mdx — full architecture walkthrough with three-layer model, 11 canonicals, three worked examples (Meta Reels / NYTimes IAB MREC + sibling HTML5 / podcast host-read), two flows for inputs-driven creative, preview as universal verification surface, brand identity via BrandRef.
• docs/creative/v2-migration.mdx (new) — concrete v1 → v2 migration paths: side-by-side translations, slot mapping table, generative format dissolution, discovery surface migration, adopter paths per role, realistic timelines.

Fixtures + fixture-validation test (Phase 3)

• static/examples/products/v2/*.json — 5 fully-valid Product reference fixtures
• tests/v2-fixture-validation.test.cjs — validates all fixtures against /schemas/core/product.json; runs via npm run test:v2-fixtures
• Schema-validation test update: replaced static format_ids assertion on product.json with the new oneOf(format_ids, format) check

What's NOT in this PR (deferred or out of scope)

• SDK codegen scaffolding — Phase 4, separate PR (TypeScript first; generates typed accessors from canonical catalog)
• Server-side flatten wrapper reference impl — lets v2 sellers derive v1 list_creative_formats shape from v2 product declarations; Phase 4
• Native canonical format — deferred to 3.2 after TemplateCreative + OpenRTB Native 1.2 audit

v1 backwards compatibility

• v1 named formats (format_id as { agent_url, id }) continue to work through 3.x and 4.x
• v1 list_creative_formats deprecated but functional; sellers SHOULD provide server-side flatten wrappers through 4.0; removed at 5.0
• Existing schemas unchanged or modified backwards-compatibly; existing producers and consumers continue to validate
• v2 product-bound declarations are opt-in; sellers migrate when their organizational reality permits

Hold reason

Changeset is minor (this lands as 3.1.0). Merging now would cut a 3.1.0 release before the rest of v2 work is ready. Branch sits open as a preview adopters can build against; merge timing aligns with the 3.1.0 beta cycle opening.

Test plan

• npm run build:schemas — clean; 510+ schemas in dist/schemas/latest/
• npm run test:schemas — 7/7
• npm run test:json-schema — 255/255 MDX JSON blocks valid
• npm run test:v2-fixtures — 5/5 reference fixtures pass strict Product validation
• Pre-commit hooks pass (test:unit, test:test-dynamic-imports, typecheck)
• Mintlify broken-link check passed

🤖 Generated with Claude Code

[bokelley]

Issue #3639 proposes aligning the buyer-side production-source enum default across all four canonicals (buyer_uploaded on image/video_hosted/audio_hosted vs buyer_pre_rendered on sponsored_placement — same concept, different name). Same surface as this PR; consider folding before merge or confirm as a follow-up.

---

Generated by Claude Code

[bokelley]

Issue #3638 proposes adding an optional runtime_status field to product-format-declaration.json — same surface as this PR; consider folding before merge or confirm as a follow-up. See issue for full rationale (short version: adopters will declare seller_pre_rendered_from_brief aspirationally during v2 rollout; without this field there's no spec expression for "declared but not wired in the adapter").

---

Generated by Claude Code

[pkras]

Ok so two things first:

1. Production-source enum asymmetry: 'buyer_uploaded' (image/video/audio) vs 'buyer_pre_rendered' (sponsored_placement) — same concept, different name #3639 and naming inconsistency

We should pick one and rename and do that before 3.1 so we don’t have to go through full deprecation cycle.

I would go with buyer_uploaded due to the fact that it’s just one rename vs three renames elsewhere. But i do admmting that buyer_pre_rendered is a better description, but this is a philosophical personal nit.

So yes, this one first - i think this consistency could be later on nicely updated with my proposal on the POV below.

2. Adopter runtime declaration honesty: 'declared on catalog, not wired in adapter' has no spec expression #3638 and coming soon

how about: adding a runtime_status with:

• stable
• preview
• declared_only

preview means the runtime exists but is imperfect. A buyer who proceeds might get 80% of what they expected. declared_only means the runtime doesn't exist at all for this path. A buyer who proceeds will hit a wall at sync_creatives so the seller's adapter simply doesn't handle it.

Buyers = trust signal

• stable aka buy with confidence, runtime will deliver
• preview aka proceed carefully, you might hit rough edges
• declared_only aka don't buy against this yet, the seller is telling you where they're headed not where they are

Sellers = honesty mechanism

• stable aka I've built and tested this end to end
• preview aka I've built it but not hardened it
• declared_only aka I've put this in my catalog because it's my roadmap, but if you try to use it today it won't work

---

My overall POV: v2 canonical format catalog doesn't account for proprietary publisher format names

The 11 canonical format types (image, video_hosted, html5, etc.) are useful machine-readable categories for buyer agents to reason about. But real sellers don't organize their inventory this way. Premium publishers and ad networks sell proprietary named formats, high-impact units with their own branding, specs, and pricing. These don't map cleanly to any canonical. The spec has platform_extensions for seller-specific extras, but that assumes you're starting from a canonical baseline. There's no good answer for a format that is genuinely novel.

Potential adoption risk: if the first question every premium publisher asks during v2 onboarding is "where does my flagship format go?" and the best answer is "extend html5 I guess," the canonical model loses credibility before it gains traction.

Two additions that would close this without complicating the core model:

1. a custom canonical: An explicit escape hatch for formats that are genuinely novel. Seller declares canonical: "custom", provides their own full format definition, no baseline assumptions applied. Buyer agents know to read the seller's description rather than inferring behavior from the canonical.
2. canonical_hint alongside display_name -> rather than one field doing two jobs, formally separate the human-facing name from the machine-readable classification:
   -display_name: "Hover by Publisher so what buyers and UIs see
   -canonical_hint: "html5" so the closest canonical for buyer agent reasoning, explicitly marked as approximate

[nastassiafulconis]

arch is solid — canonical-as-contract is the right call. inline below is the stuff i'd want fixed before 3.1 ga.

one bigger thing: the 3 surface-composed canonicals (sponsored_placement / responsive_creative / agent_placement) capture the creative envelope but miss the actual product. amazon_sponsored_products has no negatives / match types / bid mods, pmax collapses 3 surfaces into one. would treat those as rfc-grade until 2 retail-media nets ship format_schema artifacts against them. rest over slack 🙌

[nastassiafulconis]

cards is asset_type: "object" but asset-union doesn't have an object branch — pretty sure a real carousel manifest won't actually validate. plus card_shape (line 16) has no $id so there's nothing to $ref against. extract card_shape into core/assets/card-asset.json + add card to asset-union?

[bokelley]

Fixed in fbb207b — extracted card_shape into /schemas/core/assets/card-asset.json (asset_type: "card" with required media, optional headline, landing_page_url, platform_extensions, provenance), added card to asset-union.json and to the creative/asset-types/index.json registry, added card to the canonical _base.json slot asset_type enum, and changed image_carousel's cards slot from asset_type: "object" → "card".

Surfaced the structural problem you flagged was bigger than just cards: the manifest's assets patternProperties expected a single asset value per slot, which also broke responsive_creative multi-value slots (headlines, descriptions, images_landscape with min/max counts). Relaxed the patternProperties to oneOf(single asset | array of assets) on creative-manifest.json, creative-asset.json, and list-creatives-response.json — unblocks both carousel cards AND multi-value slots. Verified ad-hoc that a real carousel manifest now validates; previously it didn't.

[nastassiafulconis]

buyers can't tell deterministic-fail from "platform is nondeterministic, can't pre-validate". synthesis_failed is in description prose only (response.json:5) — not in any enum or as a discriminator here. could we add result_kind: "validated_pass" | "validated_fail" | "unvalidatable_nondeterministic" so callers can branch?

[bokelley]

Fixed in fbb207b — replaced boolean ok with result_kind: validated_pass | validated_fail | unvalidatable_nondeterministic discriminator. Buyers now branch on three meaningfully different outcomes instead of conflating "failed validation" with "platform is nondeterministic, can't pre-validate." allOf if/then enforces violations[] absent for the two non-failure result_kinds (validated_pass and unvalidatable_nondeterministic).

No consumers yet (v2 not shipped) so took the breaking shape — ok removed cleanly rather than additive. The validate-input-response description was updated to reference the three values. Negative-fixture regression test added to tests/v2-negative-fixtures.test.cjs covering: validated_pass + violations rejected, unvalidatable_nondeterministic + violations rejected, old-shape ok boolean payloads rejected.

[nastassiafulconis]

composing top-level discriminator + the allOf if/then/else (35-51) + the 12-branch oneOf feels risky. what happens if someone ships format_kind: "image" with a stray format_schema — does the discriminator forward to the image branch before the else fires? worth a fixture, or just drop the top-level discriminator (the oneOf consts already discriminate).

[bokelley]

Tested in fbb207b — wrote tests/v2-negative-fixtures.test.cjs with 7 cases on product-format-declaration. All compose correctly under AJV with discriminator+strict:false:

• format_kind:"image" + stray format_schema → rejected ✓
• format_kind:"image" + stray format_shape → rejected ✓
• format_kind:"custom" missing format_shape → rejected ✓
• format_kind:"custom" missing format_schema → rejected ✓
• bogus format_kind value → rejected ✓
• format_kind:"custom" complete (positive control) → passes ✓
• format_kind:"image" clean (positive control) → passes ✓

The composition works. The else clause in the allOf if/then/else fires regardless of how the discriminator routes — discriminator is a hint for error-message attribution, not a validation gate. Wired up as npm run test:v2-negative so future schema changes that break this composition surface as regressions.

[nastassiafulconis]

both duration fields are optional w/ no oneOf — what's precedence if a product ships both? same gap in audio_hosted, audio_daast, video_vast. either oneOf them or doc the rule.

[bokelley]

Fixed in fbb207b — documented exact-wins precedence in description prose on all four canonicals (video_hosted, audio_hosted, video_vast, audio_daast). duration_ms_exact takes precedence when both ship; SDKs SHOULD lint a warning when both fields appear; producers SHOULD pick one. Schema stays permissive (no oneOf) for back-compat with any product currently emitting both — option (b) from the punch-list discussion.

[nastassiafulconis]

this sentence broke somewhere — reads like two paragraphs got merged. the rule for when capability_id is required is the load-bearing thing here and it's buried in malformed prose, needs a rewrite.

[bokelley]

Fixed in fbb207b — rewrote the broken paragraph as a normative routing rule with a clean code block:

• format_kind selects the canonical and its slot vocabulary
• capability_id is REQUIRED on the manifest when the target product's format_options contains 2+ declarations sharing the same format_kind (without it the seller can't disambiguate)
• capability_id is OPTIONAL when each format_kind in format_options is unique — format_kind alone routes the manifest. Buyers MAY still send capability_id as a clarity hint.

The example annotates which case it is (each option here has a distinct format_kind, so capability_id is optional but recommended habit).

[nastassiafulconis]

few things off:

• manifest ships assets.video (615) but violation says assets.video_main.duration_ms
• expected: "3000-90000" + predicted: 30000 — 30000 is inside the range, claims a fail that mathematically passes
• manifest uses v1 format_id: {agent_url, id} (613) inside what should be a v2 example

adopters will copy this verbatim 😬

[bokelley]

Fixed in fbb207b — all three:

• assets.video → assets.video_main (matches the violation field path)
• predicted: 30000 → 95000 (was inside the expected 3000-90000 range, now clearly out-of-range so the validated_fail outcome is structurally consistent)
• v1 format_id removed; manifest now uses v2 format_kind: "video_hosted" shape with the proper canonical slot vocabulary

Adopters who copy the example verbatim now get a structurally honest example. Thanks for catching this — it was the showcase example for the whole validate_input primitive.

[nastassiafulconis]

few things in here:

• L33-44 swallows real load failures silently — would log+exit on parse errors, only swallow duplicate $id adds
• L99 truncate-at-10 hides the real error when the 12-branch oneOf in product-format-declaration emits noise from non-matching branches
• only validates against product envelope; canonicals have additionalProperties:true (per _base.json:102) so a typo in params slips through silently. fixtures are normative — run them through the per-canonical schemas in strict mode too?

[bokelley]

Fixed in fbb207b — all three:

(a) Schema parse errors during load now log + exit 2 (was: silently swallowed in a bare catch {}). Only the addSchema duplicate-$id error stays tolerated — that's benign during partial dist/ rebuilds when the same schema lands in both source and dist. The new code distinguishes the two failure modes explicitly.

(b) Removed truncate-at-10. The 12-branch product-format-declaration emits one error per non-matching branch, and the relevant failure is often the LAST branch's error (the matching discriminator branch). Full output is necessary to find the actual cause. Each error now also reports the schemaPath so reviewers can trace which branch fired.

(c) Per-canonical strict-mode validation runs against each format_options[i].params using a separate AJV instance with additionalProperties-tolerance disabled. Surfaces typos in params that the product envelope (additionalProperties:true) lets pass. Custom format_kind excluded — its params shape is governed by the seller's fetched format_schema, not by AdCP-side schema. Strict-mode warnings are non-fatal today (they don't fail CI) because additionalProperties:true is load-bearing for platform_extensions and seller-specific narrowings; warnings let fixture authors catch typos before merge.

[bokelley]

@pkras Thanks for the substantive review — all three of your points landed across the recent commits. Quick map for each:

1. #3639 (naming inconsistency) — picked buyer_uploaded per your call (one rename vs three; agreed the framing nit on "uploaded" reads slightly off for catalog-keyed items but the framing is called out explicitly in the description so readers don't trip on it). Landed in b3c29bc17. All four production-source fields (audio_source, image_source, video_source, item_production_model) now share the same 4-value enum default; SDK codegen emits a single shared enum.

2. #3638 (runtime_status) — landed exactly as you proposed, b3c29bc17: runtime_status: stable | preview | declared_only on ProductFormatDeclaration, distinct from canonical-level status (which is about spec maturity). The trust-signal / honesty-mechanism framing you wrote made it into the description prose. Documented in v2-overview "Two stability axes" section and in the migration walkthrough's sales-agent step 3.

3. Custom format / canonical_hint / display_name (POV) — your proposal substantively shipped in 1cc7e2016. format_kind: "custom" is the explicit escape hatch you described for genuinely novel formats. format_shape (from a vocabulary registry — multi_placement_takeover, branded_content, ar_lens, etc.) is the canonical_hint analog: machine-readable classification, separate from human-facing name, explicitly marked as recognized-pattern-but-not-yet-canonical. The crucial addition (raised by a follow-up review): format_schema is a URI+digest reference to the seller's fetchable schema, so buyer agents can reason structurally about novel formats without per-seller integration code. Same hosting / caching mechanic as platform_extensions.

The promotion path you implied — recognized patterns become canonicals as adoption matures — is in the format-shape registry's governance rules. Promotion to canonical happens when a format_shape entry sees 2+ adopters with substantively similar format_schema content for 90+ days. Tracking queue at #3666.

The display_name idea (separate human-facing name field on declarations) is one I haven't landed yet — products carry name already, and the format_shape registry entries carry description / typical_use, but I haven't added a display_name on the format declaration itself for UI presentation. Worth a follow-up if the lack surfaces in dashboard / catalog UIs. Want to scope that as a new issue? Easy add if there's adopter pull.

[bokelley]

Issue #3765 proposes relaxing product.json from oneOf(format_ids, format) to allow both fields co-present — v2 format as primary, format_ids as v1 fallback for mixed buyer fleets during transition. Same product.json surface as this PR; consider folding before merge or confirm follow-up.

---

Generated by Claude Code

[bokelley]

Issue #3767 proposes a v1↔v2 canonical mapping registry (static/registries/v1-canonical-mapping.json) + canonical / canonical_parameters fields on v1 format.json declarations — same surface as this PR (which already adds asset_group_id to format.json slot declarations and owns the schema surface this would extend). Consider folding before merge or confirm as a follow-up PR once the 3.1 beta cycle opens.

---

Generated by Claude Code

[pkras]

on the question: should we add a field specifically for that so UIs have a clean, seller-controlled label to show buyers? - yes, maybe "label" or "display_name".

[bokelley]

@pkras @bokelley — consensus noted on adding a seller-controlled display field to product-format-declaration.json. Two questions before acting:

1. Field name: display_name matches the naming @bokelley used in the prior comment and is self-describing on the wire; label is shorter but more generic. Which do you prefer?
2. Where: fold into this PR before the 3.1 beta cycle opens, or open a follow-up issue now (as @bokelley originally suggested) and defer to a separate PR?

Happy to implement either way once you land on a name.

---

Generated by Claude Code

[pkras]

1. Display name it is then
2. i'd say 3.1

[bokelley]

Done — display_name (optional string) added to ProductFormatDeclaration in d7faae4f. No machine semantics; buyer agents continue to route on format_kind and capability_id. The NYTimes custom-format example in the schema now shows it in use ("display_name": "Homepage Takeover — Premium Sponsorship").

---

Generated by Claude Code

[bokelley]

Noted — display_name landed in d7faae4 as an optional, non-semantic string on ProductFormatDeclaration. No wire impact; routing still on format_kind / capability_id. The NYTimes example in the schema makes the intended use clear.

---

Generated by Claude Code

[bokelley]

@nastassiafulconis on the bigger thing — "the 3 surface-composed canonicals (sponsored_placement / responsive_creative / agent_placement) capture the creative envelope but miss the actual product" — addressed at the meta level in 4bbce5893.

You were right but the fix isn't per-canonical demotion. v2 itself is in preview through the 3.1 beta cycle, so claiming ANY canonical is stable right now is a category confusion — stable-within-preview is incoherent. The PR's previous status differentiation (9 stable + 2 preview) implied locked contracts that don't actually exist yet.

Concrete reframe:

• Every canonical is preview while v2 is preview. The status field exists for future use; per-canonical differentiation kicks in at 3.1 GA, not before. Default flipped from stable to preview.
• At GA, the working group promotes individual canonicals based on adopter evidence (2+ adopters, 90 days stable params, defined tracking model — same rubric we already documented).
• The 9 IAB-anchored canonicals (image, html5, display_tag, image_carousel, video_hosted, video_vast, audio_hosted, audio_daast, sponsored_placement) are expected to clear the rubric quickly because they sit on top of established industry standards.
• The 3 surface-composed canonicals (responsive_creative, agent_placement, sponsored_placement — the latter for exactly the gap you flagged: amazon_sponsored_products' negatives / match types / bid mods aren't in the canonical because the canonical is the creative envelope, not the bidding/matching layer; PMax's 3-surface collapse is the same shape) need adopter-shipped format_schema evidence before promotion. They stay preview past GA until 2 retail-media nets ship real declarations against them.

Your bar ("2 retail-media nets ship format_schema artifacts") is now structurally what the rubric enforces — no special-case demotion needed.

On the scope question (creative envelope vs bidding rules / match types / bid mods): the canonical's job is to describe what assets the buyer ships and how the surface renders them. Bidding rules, match types, negatives, surface-specific behaviors are separate domains that live on the package / proposal / extension surfaces, not on format. Adding them to format would conflate two things. But you're right that adopters reading amazon_sponsored_products will reasonably wonder "where do I declare match_type?" — that's a docs gap I'll close in a follow-up. Each surface-composed canonical needs an explicit scope note saying "this canonical describes [X creative envelope]; bidding/matching/inventory parameters live elsewhere."

Filing that as a follow-up so it doesn't gate this PR. Ping me when you want to chat through the bigger architectural question on Slack — happy to keep digging on whether/how AdCP should ever extend into the bidding layer.

[bokelley]

@nastassiafulconis a few replies in one:

On #3765 / #3767: both already in this branch — landed in a8228b666f. A1 (anyOf relaxation + dual-emission contract) and A2 (canonical mapping registry at static/schemas/source/registries/v1-canonical-mapping.json + canonical / canonical_parameters on v1 format.json + normative SDK projection rules in v2-migration.mdx). No separate branch needed.

On pushing to the same branch: yes, fine. bokelley/v2-phase1-vocab-scenes-delivery is the v2 trunk for everything pre-GA. Direct push welcome.

On bidding-layer scoping + cross-surface collapse: agree they're two separate axes (order logic vs product topology). Filed as two RFCs so they're independent design calls but tracked together:

• #4548 — Order-logic scoping (Product.targeting_capabilities for discovery + Package.targeting for buy-time configuration). Per-axis sub-objects (keyword_targeting / audience_targeting / bid_modifiers / geo_targeting / pacing), not one umbrella.
• #4549 — Product topology (Product.sub_products[] for PMax-class meta-products that fan out across multiple surfaces with per-surface policies). Different shape, different RFC.

Both targeted at 3.1 GA (not necessarily this PR). My lean on each is in the RFC body; open questions for design discussion are also there. Cross-linked between each other so they don't get conflated.

On Pia sync: nothing else from me — see what comes out of the sync and ping me if you want me drafting anything specific on agentic SOW.