feat: AXE-27 add unified assets field for better asset discovery

.changeset/assets-discovery.md

@@ -0,0 +1,11 @@
+---
+"adcontextprotocol": minor
+---
+
+Add unified `assets` field to format schema for better asset discovery
+
+- Add new `assets` array to format schema with `required` boolean per asset
+- Deprecate `assets_required` (still supported for backward compatibility)
+- Enables full asset discovery for buyers and AI agents to see all supported assets
+- Optional assets like impression trackers can now be discovered and used
+

.github/workflows/broken-links.yml

@@ -2,9 +2,9 @@ name: Check for Broken Links
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, develop, '2.6.x' ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, develop, '2.6.x' ]
 
 jobs:
   broken-links:

.github/workflows/changeset-check.yml

@@ -2,7 +2,7 @@ name: Changeset Check
 
 on:
   pull_request:
-    branches: [main]
+    branches: [main, '2.6.x']
 
 jobs:
   check:

.github/workflows/check-testable-snippets.yml

@@ -2,6 +2,7 @@ name: Check Testable Snippets
 
 on:
   pull_request:
+    branches: [main, '2.6.x']
     paths:
       - 'docs/**/*.md'
       - 'docs/**/*.mdx'
@@ -26,7 +27,7 @@ jobs:
 
           if [ -s changed_files.txt ]; then
             echo "📋 Checking documentation changes for testable snippets..."
-            node scripts/check-testable-snippets.js
+            node scripts/check-testable-snippets.cjs
           else
             echo "✓ No documentation files changed"
           fi

.github/workflows/release.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches:
       - main
+      - '2.6.x'
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 

.github/workflows/schema-validation.yml

@@ -2,9 +2,9 @@ name: JSON Schema Validation
 
 on:
   push:
-    branches: [ main, develop ]
+    branches: [ main, develop, '2.6.x' ]
   pull_request:
-    branches: [ main, develop ]
+    branches: [ main, develop, '2.6.x' ]
 
 jobs:
   schema-validation:

CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 2.6.0
+
+### Minor Changes
+
+- Add unified `assets` field to format schema for better asset discovery
+
+  **Schema Changes:**
+
+  - **format.json**: Add new `assets` array field that includes both required and optional assets
+  - **format.json**: Deprecate `assets_required` (still supported for backward compatibility)
+
+  **Rationale:**
+
+  Previously, buyers and AI agents could only see required assets via `assets_required`. There was no way to discover optional assets that enhance creatives (companion banners, third-party tracking pixels, etc.).
+
+  Since each asset already has a `required` boolean field, we introduced a unified `assets` array where:
+  - `required: true` - Asset MUST be provided for a valid creative
+  - `required: false` - Asset is optional, enhances the creative when provided
+
+  This enables:
+  - **Full asset discovery**: Buyers and AI agents can see ALL assets a format supports
+  - **Richer creatives**: Optional assets like impression trackers can now be discovered and used
+  - **Cleaner schema**: Single array instead of two separate arrays
+
+  **Example:**
+
+  ```json
+  {
+    "format_id": { "agent_url": "https://creative.adcontextprotocol.org", "id": "video_30s" },
+    "assets": [
+      { "item_type": "individual", "asset_id": "video_file", "asset_type": "video", "required": true },
+      { "item_type": "individual", "asset_id": "end_card", "asset_type": "image", "required": false },
+      { "item_type": "individual", "asset_id": "impression_tracker", "asset_type": "url", "required": false }
+    ]
+  }
+  ```
+
+  **Migration:** Non-breaking change. `assets_required` is deprecated but still supported. New implementations should use `assets`.
+
 ## 2.5.1
 
 ### Patch Changes

docs/creative/asset-types.mdx

@@ -338,15 +338,17 @@ The keys in the assets object correspond to the `asset_id` values defined in the
 
 ## Usage in Creative Formats
 
-Creative formats specify their required assets using `assets_required` (an array):
+Creative formats specify their assets using the `assets` array. Each asset has a `required` boolean:
+- **`required: true`** - Asset MUST be provided for a valid creative
+- **`required: false`** - Asset is optional, enhances the creative (e.g., companion banners, third-party tracking pixels)
 
 ```json
 {
   "format_id": {
     "agent_url": "https://creative.adcontextprotocol.org",
     "id": "video_15s_hosted"
   },
-  "assets_required": [
+  "assets": [
     {
       "item_type": "individual",
       "asset_id": "video_file",
@@ -359,11 +361,41 @@ Creative formats specify their required assets using `assets_required` (an array
         "acceptable_resolutions": ["1920x1080", "1280x720"],
         "max_file_size_mb": 30
       }
+    },
+    {
+      "item_type": "individual",
+      "asset_id": "impression_tracker",
+      "asset_type": "url",
+      "required": false,
+      "requirements": {
+        "format": ["url"],
+        "description": "Third-party impression tracking pixel URL"
+      }
+    }
+  ],
+
+  // DEPRECATED: Use "assets" above instead. Kept for backward compatibility.
+  "assets_required": [
+    {
+      "item_type": "individual",
+      "asset_id": "video_file",
+      "asset_type": "video",
+      "requirements": {
+        "duration_seconds": 15,
+        "acceptable_formats": ["mp4"],
+        "acceptable_codecs": ["h264"],
+        "acceptable_resolutions": ["1920x1080", "1280x720"],
+        "max_file_size_mb": 30
+      }
     }
   ]
 }
 ```
 
+<Note>
+**Backward Compatibility**: The `assets_required` field is deprecated but still supported. Existing implementations can continue using `assets_required` for required assets only. New implementations should use `assets` with the `required` boolean for full asset discovery.
+</Note>
+
 ## Repeatable Asset Groups
 
 For formats with asset sequences (like carousels, slideshows, stories), see the [Carousel & Multi-Asset Formats guide](/docs/creative/channels/carousels) for complete documentation on repeatable asset group patterns.

docs/creative/formats.mdx

@@ -222,7 +222,7 @@ Formats are JSON objects with the following key fields:
   },
   "name": "30-Second Hosted Video",
   "type": "video",
-  "assets_required": [
+  "assets": [
     {
       "item_type": "individual",
       "asset_id": "video_file",
@@ -234,6 +234,53 @@ Formats are JSON objects with the following key fields:
         "format": ["MP4"],
         "resolution": ["1920x1080", "1280x720"]
       }
+    },
+    {
+      "item_type": "individual",
+      "asset_id": "end_card_image",
+      "asset_type": "image",
+      "asset_role": "end_card",
+      "required": false,
+      "requirements": {
+        "dimensions": "1920x1080",
+        "format": ["PNG", "JPG"]
+      }
+    },
+    {
+      "item_type": "individual",
+      "asset_id": "companion_banner",
+      "asset_type": "image",
+      "asset_role": "companion",
+      "required": false,
+      "requirements": {
+        "dimensions": "300x250",
+        "format": ["PNG", "JPG", "GIF"]
+      }
+    },
+    {
+      "item_type": "individual",
+      "asset_id": "impression_tracker",
+      "asset_type": "url",
+      "asset_role": "third_party_tracking",
+      "required": false,
+      "requirements": {
+        "description": "Third-party impression tracking pixel URL"
+      }
+    }
+  ],
+
+  // DEPRECATED: Use "assets" above instead. Kept for backward compatibility.
+  "assets_required": [
+    {
+      "item_type": "individual",
+      "asset_id": "video_file",
+      "asset_type": "video",
+      "asset_role": "hero_video",
+      "requirements": {
+        "duration": "30s",
+        "format": ["MP4"],
+        "resolution": ["1920x1080", "1280x720"]
+      }
     }
   ]
 }
@@ -243,10 +290,24 @@ Formats are JSON objects with the following key fields:
 - **format_id**: Unique identifier (may be namespaced with `domain:id`)
 - **agent_url**: The creative agent authoritative for this format
 - **type**: Category (video, display, audio, native, dooh, rich_media)
-- **assets_required**: Array of asset specifications
+- **assets**: Array of all asset specifications with `required` boolean indicating mandatory vs optional
+- **assets_required**: *(Deprecated)* Array of required asset specifications - use `assets` instead
 - **asset_role**: Identifies asset purpose (hero_image, logo, cta_button, etc.)
 - **renders**: Array of rendered outputs with dimensions - see below
 
+### Asset Discovery
+
+The `assets` array enables comprehensive asset discovery. Each asset has a `required` boolean:
+
+- **`required: true`** - Asset MUST be provided for a valid creative
+- **`required: false`** - Asset is optional, enhances the creative when provided (e.g., companion banners, third-party tracking pixels)
+
+This unified approach helps creative tools and AI agents understand the full capabilities of a format, enabling richer creative experiences when optional assets are available while clearly indicating minimum requirements.
+
+<Note>
+**Backward Compatibility**: The `assets_required` field is deprecated but still supported. Existing implementations can continue using `assets_required` for required assets only. New implementations should use `assets` with the `required` boolean on each asset for full asset discovery.
+</Note>
+
 ### Rendered Outputs and Dimensions
 
 Formats specify their rendered outputs via the `renders` array. Most formats produce a single render, but some (companion ads, adaptive formats, multi-placement) produce multiple renders:

docs/creative/implementing-creative-agents.mdx

@@ -100,7 +100,7 @@ Creative agents must implement these two tasks:
 Return all formats your agent defines. This is how buyers discover what creative formats you support.
 
 **Key responsibilities:**
-- Return complete format definitions with all `assets_required`
+- Return complete format definitions with all `assets` (both required and optional)
 - Include your `agent_url` in each format
 - Use proper namespacing for `format_id` values
 
@@ -169,7 +169,7 @@ When validating manifests:
 
 When updating format definitions:
 
-- **Additive changes** (new optional assets) are safe
+- **Additive changes** (new optional assets with `required: false` in `assets`) are safe
 - **Breaking changes** (removing assets, changing requirements) require new format_id
 - Consider versioning: `youragency.com:format_name_v2`
 - Maintain backward compatibility when possible

docs/creative/task-reference/list_creative_formats.mdx

@@ -56,7 +56,7 @@ Formats may produce multiple rendered pieces (e.g., video + companion banner). D
 
 | Field | Description |
 |-------|-------------|
-| `formats` | Array of full format definitions (format_id, name, type, requirements, assets_required, renders) |
+| `formats` | Array of full format definitions (format_id, name, type, requirements, assets, assets_required, renders) |
 | `creative_agents` | Optional array of other creative agents providing additional formats |
 
 See [Format schema](https://adcontextprotocol.org/schemas/v2/core/format.json) for complete format object structure.
@@ -421,7 +421,8 @@ Each format includes:
 | `name` | Human-readable format name |
 | `type` | Format type (audio, video, display, dooh) |
 | `requirements` | Technical requirements (duration, file types, bitrate, etc.) |
-| `assets_required` | Array of required assets with specifications |
+| `assets` | Array of all assets with `required` boolean indicating mandatory vs optional |
+| `assets_required` | *(Deprecated)* Array of required assets - use `assets` instead |
 | `renders` | Array of rendered output pieces (dimensions, role) |
 
 ### Asset Roles

package.json

@@ -1,6 +1,6 @@
 {
   "name": "adcontextprotocol",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "private": true,
   "type": "module",
   "scripts": {