feat(creative): v2 Phase 1 — asset_group vocabulary, scenes schema, delivery_type, video.mdx fix#3307
Open
feat(creative): v2 Phase 1 — asset_group vocabulary, scenes schema, delivery_type, video.mdx fix#3307
Conversation
…_type, video.mdx fix First PR implementing the v2 creative formats RFC (#3305). Backwards-compatible additions only. - Add static/schemas/source/core/asset-group-vocabulary.json (canonical asset_group_id registry — 7 existing catalog vocab entries + 12 audit-driven additions, with landing_page_url canonicalizing 6 v1 alias names) - Add static/schemas/source/creative/scenes.json (typed scene-by-scene structure for build_creative input; renamed from "storyboard" to avoid collision with the testing-harness storyboard concept) - Add optional delivery_type discriminator to html-asset.json and javascript-asset.json via oneOf (inline branch matches v1 producers without delivery_type; url branch lets zip URLs and 3P tag URLs round-trip cleanly) - Fix docs/creative/channels/video.mdx VAST/VPAID format examples (asset_type "url"+asset_role "vast_url" → asset_type "vast"; VPAID uses asset_type "vast" with vpaid_enabled: true) Tracks #3305 (v2 RFC). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…register vocabulary in source index Two follow-ups from independent expert review of #3307: - audio.mdx:200 had the same bug pattern as video.mdx (caught by code-reviewer): the audio_30s_vast manifest example used asset_type "url" + url_type "tracker" for what should be a VAST audio tag. Corrected to asset_type "vast" with delivery_type "url"; renamed slot key from "vast_url" to "vast_tag" for clarity. - Register asset-group-vocabulary.json under core schemas and scenes.json under creative.build_inputs in static/schemas/source/index.json so the new schemas are discoverable via the public registry. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CI caught: when I changed asset_type from "url" to "vast" in video.mdx:410, the vast-asset-requirements.json schema started applying — it requires vast_version as a single string from the enum, not an array. Original doc had vast_version: ["3.0", "4.0", "4.1", "4.2"] which the looser "url" asset_type tolerated. Fix: vast_version: "4.2" (matches the manifest example at line 511). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New schemas (asset-group-vocabulary.json, scenes.json) and a new optional field (delivery_type on html/javascript) are additive features. Patch is reserved for bug fixes only. Aligns with the RFC's "3.1 preview track" framing — Phase 1 is the first PR toward 3.1.0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 1 design scrub. The delivery_type oneOf addition on html/javascript schemas wasn't earning its keep — URL-delivered HTML/JS already routes through url-asset.json with appropriate url_type. The real gap was a zip asset type for HTML5 banner bundles, which is genuinely missing from the registry today. - Revert delivery_type from html-asset.json and javascript-asset.json (back to inline-only, matching v1 behavior) - Add static/schemas/source/core/assets/zip-asset.json — new asset type for bundled HTML5 banners (url + max_file_size_kb + entry_point + allowed_inner_extensions + backup_image_url + sha256 digest) - Register zip in creative/asset-types/index.json - Add IndividualZipAsset / GroupZipAsset branches to format.json - Add zip-asset.json $ref to creative-manifest.json, creative-asset.json, creative/list-creatives-response.json, offering-asset-group.json - Clarify scenes.json description re: reference-asset.json purpose: "storyboard" (related but different concept — structured plan vs visual reference asset) - Rename changeset accordingly Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…eclaration, validate_input, build capabilities Foundation for the v2 RFC architecture (#3305). Backwards-compatible additions only — v1 named formats and v1 producers continue to work unchanged. **11 canonical format definitions** at static/schemas/source/formats/canonical/: - image (static), html5 (interactive bundle), display_tag (3P-served) - image_carousel (multi-card, polymorphic items) - video_hosted (direct file, OM-SDK + external trackers) - video_vast (VAST tag, inherent VAST event tracking) - audio_hosted (direct file) - audio_daast (DAAST tag) - sponsored_placement (retail-media catalog-driven, deterministic composition) - asset_pool_composed (Google PMax family, algorithmic composition) - brand_mention (text/audio AI-surface composition) - _base.json with shared fields (composition_model, provenance_required, platform_extensions, tracking_extensions) Each canonical bakes in its tracking model and references the asset_group_id vocabulary shipped in Phase 1. Format-keyed-by-name structure (no canonical discriminator field). **ProductFormatDeclaration** (static/schemas/source/core/product-format-declaration.json): keyed by canonical format name with minProperties: 1, maxProperties: 1, no additionalProperties — exactly one canonical key per declaration. Includes worked examples for Meta Reels, IAB MREC, podcast host-read. **Product/manifest additive fields:** - product.json: optional `format` field (v2 inline declaration), optional `build_capability_ref` (for products requiring agent-produced creative). v1 format_ids path remains supported. - creative-manifest.json: optional `brand` field (resolves brand.json) and `brand_kit_override` (explicit override for missing/stale brand.json). **Build capabilities:** - build-capability.json: schema for creative agents declaring what canonical formats they can build, with parameter narrowing and typed inputs. - build-capability-ref.json: reference type used on products. - get_adcp_capabilities response: added `creative.creative_build_capabilities` array. Replaces v1 list_creative_formats discovery surface for creative agents. **Platform extension references:** - platform-extension-ref.json: URI + content-digest reference to platform extension definitions. Bundled in get_products responses to avoid extra fetches; SDK caches by URI@digest. **validate_input tool:** - validate-input-request.json, validate-input-response.json, validate-input-result.json: cheap dry-run primitive for validating a manifest against canonical formats and/or specific products. predicted field carries pre-flight estimates; no protocol state for orphaned out-of-spec artifacts (nondeterministic platforms run their own QA loop). Tracks #3305 (v2 RFC). Phase 1 (#3307) primitives unblock this Phase 2 surface; together they let buyers and adopters point at one preview branch and build end-to-end against the v2 spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… MREC, podcast host-read) Adopter-facing documentation for the v2 RFC architecture (#3305) shipping in the #3307 preview branch. Walks through the canonical-formats-narrowed- by-products model with three concrete worked examples that illustrate the full surface: - Meta Reels narrowing video_hosted with platform extensions - IAB Medium Rectangle (300x250) narrowing image, plus a sibling NYTimes HTML5 banner narrowing html5 (different canonical for different tracking model) - The Daily 30s host-read narrowing audio_hosted with build_capability_ref pointing at the publisher's creative agent Includes worked validate_input flow, brand_kit_override usage, platform extension distribution explanation (URI+digest bundled in get_products), and explicit notes on what's NOT in v2 (brand safety frameworks, universal macros schema, destination_kinds schema, cta_vocabulary, list_build_ capabilities tool — all dropped per design scrub). Examples are marked test=false because they intentionally show only the v2-specific surface, not the full Product schema (which would clutter the illustrations with unrelated required fields like reporting_capabilities, delivery_type, etc.). Adopters can refer to actual reference fixtures for fully-valid product examples. Tracks #3305 (v2 RFC). Doc lives at /docs/creative/v2-overview alongside existing creative docs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… asset_group_id to format slots; expand vocabulary aliases Simplifications from the working-example walkthrough: 1. Drop build_capability and build_capability_ref schemas + product field. The input contract folds into the format declaration as a parameter. External creative agents are invisible to the buyer in the typical case — buyer-seller boundary is the only relationship the protocol models. 2. Add `inputs` field to canonical format _base.json. Tells the buyer what the format requires (script for host-read, creative_brief for generative, voice_id for TTS variation). When absent, format accepts only buyer-uploaded creative. 3. Rename creative.creative_build_capabilities → creative.supported_formats on get_adcp_capabilities response. Drops "build_" framing on discovery surface naming. Each entry uses ProductFormatDeclaration shape — one primitive, two homes (sales-side inline on products, creative-agent- side as supported_formats list). 4. Add `asset_group_id` field to format.json baseIndividualAsset and baseGroupAsset. Lets v1 reference creatives declare their canonical equivalents inline (e.g., slot click_url → asset_group_id landing_page_url). Strengthens v1↔v2 migration bridge. 5. Expand `aliases` arrays in asset-group-vocabulary.json with audit- grounded sets for headlines, descriptions, images_landscape, images_vertical, images_square, logo, video, audio. 6. Update v2-overview.mdx — host-read example uses inline inputs, two- flow explanation (buyer pre-produces via build_creative on a creative agent → sync_creatives, OR sync_creatives directly with inputs → seller produces internally). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First PR implementing the v2 creative formats RFC (#3305). Backwards-compatible additions only — no v1 producers are affected.
Summary
asset-group-vocabulary.json— canonicalasset_group_idregistry: 7 existing catalog entries + 12 audit-driven additions. Canonicalizeslanding_page_url(with 6 v1 alias names:click_url,link,final_url,link_url,click_through_url,landing_url).scenes.json— typed scene-by-scene structure forbuild_creativeinput. Renamed from "storyboard" to avoid collision with the testing-harness storyboard concept.delivery_typeon html-asset.json and javascript-asset.json — optional discriminator viaoneOf. Inline branch matches v1 producers (nodelivery_type,contentrequired); url branch lets HTML5 zip URLs and 3P display tag URLs round-trip cleanly. Mirrors VAST/DAAST naming convention.asset_type: "url"+asset_role: "vast_url"/"vpaid_url", contradicting the schema-correctasset_type: "vast"used elsewhere in the same file. VPAID examples now useasset_type: "vast"withvpaid_enabled: true.Why patch
Schema additions and a doc bugfix; no breaking changes to the published spec.
v1 backwards compatibility
{ asset_type: "html", content: "..." }(nodelivery_type) continue to validate via the inline branch.asset_group_idvalues remain valid for platform-specific extensions. Validators MAY emit soft warnings on non-canonical usage.offering-asset-group.json, format definitions, etc.) are unchanged — they continue to use free-stringasset_group_idvalues; the new registry codifies what's already in use.Tracks
ProductFormatDeclarationschema (Phase 2),validate_input+preview_creativeupdates (Phase 3), SDK codegen (Phase 4)Test plan
npm run build:schemassucceeds; new schemas appear indist/schemas/latest/npm run test:schemas— all 7 validation tests pass (492 schemas)npm run test:examples— all 34 example tests passtest:unit,test:test-dynamic-imports,typecheck)🤖 Generated with Claude Code