From bac27483009c5c8377a866a016027dc2ba493160 Mon Sep 17 00:00:00 2001 From: garvitkaushik-123 Date: Wed, 17 Jun 2026 22:41:19 +0530 Subject: [PATCH] feat: add reference_assets to product_card_detailed Adds a typed `reference_assets` array to `product_card_detailed` so sellers can surface coverage maps, sample renders, environment photos, and media kits through a recognized schema slot rather than opaque extension fields. New schema: core/product-card-reference-asset.json - role enum: coverage_map, sample_render, environment_photo, media_kit, logo, other - asset: discriminated union over image, video, markdown, url assets - role_label: required when role is "other" Non-breaking: all fields optional, existing consumers unaffected. Closes #5539 Co-Authored-By: Claude Opus 4.6 --- .changeset/product-card-reference-assets.md | 5 ++ .../product-discovery/media-products.mdx | 70 +++++++++++++++++++ .../core/product-card-reference-asset.json | 43 ++++++++++++ static/schemas/source/core/product.json | 7 ++ 4 files changed, 125 insertions(+) create mode 100644 .changeset/product-card-reference-assets.md create mode 100644 static/schemas/source/core/product-card-reference-asset.json diff --git a/.changeset/product-card-reference-assets.md b/.changeset/product-card-reference-assets.md new file mode 100644 index 0000000000..541f5134db --- /dev/null +++ b/.changeset/product-card-reference-assets.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": minor +--- + +Add `reference_assets` array to `product_card_detailed` for typed seller collateral (coverage maps, sample renders, environment photos, media kits). New schema: `core/product-card-reference-asset.json`. diff --git a/docs/media-buy/product-discovery/media-products.mdx b/docs/media-buy/product-discovery/media-products.mdx index 0c2b89ed74..11de5cc21f 100644 --- a/docs/media-buy/product-discovery/media-products.mdx +++ b/docs/media-buy/product-discovery/media-products.mdx @@ -889,6 +889,76 @@ When displaying products in UIs, clients should follow this fallback order: This ensures a consistent user experience regardless of what product metadata is available. +### Reference Assets + +Sellers can attach typed collateral to `product_card_detailed` via the `reference_assets` array. Each entry carries a semantic `role` and a canonical asset payload, giving buyer agents a recognized slot to find and present seller-curated visuals — coverage maps, sample renders, environment photos, and media kits. + +This is distinct from `hero_image` and `carousel_images`, which are display-oriented. `reference_assets` is for typed collateral that buyers may inspect or use for planning. + +**Supported roles:** + +| Role | Description | +|------|-------------| +| `coverage_map` | Geographic or audience reach visualization | +| `sample_render` | Mockup of ad placement in context | +| `environment_photo` | Photo of the physical or digital environment | +| `media_kit` | Downloadable media kit or spec sheet | +| `logo` | Seller or property logo | +| `other` | Seller-defined role (provide `role_label`) | + +**Example:** + +```json +{ + "product_card_detailed": { + "title": "Downtown Commuter Screens", + "description": "High-traffic digital screens in metro station concourses...", + "hero_image": { + "asset_type": "image", + "url": "https://cdn.example.com/products/metro_hero.jpg", + "width": 1920, + "height": 1080, + "alt_text": "Metro station digital screen" + }, + "reference_assets": [ + { + "role": "coverage_map", + "asset": { + "asset_type": "image", + "url": "https://assets.example.com/maps/downtown-coverage.png", + "width": 1600, + "height": 1000, + "alt_text": "Coverage map for downtown commuter screens" + }, + "description": "Shows all screen locations across the downtown metro network" + }, + { + "role": "sample_render", + "asset": { + "asset_type": "video", + "url": "https://assets.example.com/previews/station-takeover.mp4", + "width": 1080, + "height": 1920 + }, + "description": "15-second sample of a full station takeover" + }, + { + "role": "environment_photo", + "asset": { + "asset_type": "image", + "url": "https://assets.example.com/photos/concourse-evening.jpg", + "width": 2400, + "height": 1600, + "alt_text": "Evening foot traffic at Central Station concourse" + } + } + ] + } +} +``` + +Each asset uses the canonical asset types (`image`, `video`, `markdown`, `url`) — the same primitives used throughout AdCP creative schemas. + ## Proposals Publishers can return **proposals** alongside products - structured media plans with budget allocations that buyers can execute through a defined path. Committed proposals execute directly; draft proposals must be finalized first. diff --git a/static/schemas/source/core/product-card-reference-asset.json b/static/schemas/source/core/product-card-reference-asset.json new file mode 100644 index 0000000000..0cc18e83bd --- /dev/null +++ b/static/schemas/source/core/product-card-reference-asset.json @@ -0,0 +1,43 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/core/product-card-reference-asset.json", + "title": "Product Card Reference Asset", + "description": "Typed seller collateral for buyer-facing product cards. Each entry carries a semantic role (coverage_map, sample_render, etc.) and a canonical asset payload. Distinct from hero_image/carousel_images (display-oriented) and from core/reference-asset.json (creative-generation oriented).", + "type": "object", + "properties": { + "role": { + "type": "string", + "enum": [ + "coverage_map", + "sample_render", + "environment_photo", + "media_kit", + "logo", + "other" + ], + "description": "Semantic role of this asset. coverage_map: geographic or audience reach visualization; sample_render: mockup of ad placement in context; environment_photo: photo of the physical or digital environment; media_kit: downloadable media kit or spec sheet; logo: seller or property logo; other: seller-defined role (provide role_label)." + }, + "role_label": { + "type": "string", + "description": "Human-readable label for the asset role. Required when role is 'other'; optional otherwise." + }, + "asset": { + "oneOf": [ + { "$ref": "/schemas/core/assets/image-asset.json" }, + { "$ref": "/schemas/core/assets/video-asset.json" }, + { "$ref": "/schemas/core/assets/markdown-asset.json" }, + { "$ref": "/schemas/core/assets/url-asset.json" } + ], + "description": "The asset payload, discriminated on asset_type (image, video, markdown, url)." + }, + "description": { + "type": "string", + "description": "Optional human-readable context about this asset." + } + }, + "required": [ + "role", + "asset" + ], + "additionalProperties": true +} diff --git a/static/schemas/source/core/product.json b/static/schemas/source/core/product.json index efc3b8a5ff..fd3c81c3b4 100644 --- a/static/schemas/source/core/product.json +++ b/static/schemas/source/core/product.json @@ -422,6 +422,13 @@ "cta_label": { "type": "string", "description": "Call-to-action button label." + }, + "reference_assets": { + "type": "array", + "description": "Typed seller collateral for buyer planning — coverage maps, sample renders, environment photos, media kits. Distinct from hero_image/carousel_images, which are display-oriented.", + "items": { + "$ref": "/schemas/core/product-card-reference-asset.json" + } } }, "additionalProperties": true