feat: add reference_assets to product_card_detailed

.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`.

docs/media-buy/product-discovery/media-products.mdx

@@ -964,6 +964,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.

static/schemas/source/core/product-card-reference-asset.json

@@ -0,0 +1,63 @@
+{
+  "$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"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "role": {
+            "type": "string",
+            "const": "other"
+          }
+        },
+        "required": [
+          "role"
+        ]
+      },
+      "then": {
+        "required": [
+          "role_label"
+        ]
+      }
+    }
+  ],
+  "additionalProperties": true
+}

static/schemas/source/core/product.json

@@ -455,6 +455,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