Merge pull request #1548 from adcontextprotocol/EmmaLouise2018/fix-v2-schema-links

fix: update schema links from v2 to v3 across docs

Author: EmmaLouise2018

.changeset/fix-dist-versioned-links.md

@@ -1,4 +1,4 @@
 ---
 ---
 
-Fix internal links and schema references in dist doc snapshots to point to their own versioned paths instead of the live /docs/ tree.
+Add CI check to detect stale schema version references in docs, preventing outdated /schemas/v{old}/ links from being merged.

.changeset/fix-v2-schema-links.md

@@ -0,0 +1,4 @@
+---
+---
+
+Update all docs schema references from /schemas/v2/ to /schemas/v3/ across media-buy, signals, creative, governance, and building docs.

.github/workflows/check-schema-links.yml

@@ -17,6 +17,33 @@ jobs:
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
+      - name: Check for stale schema version references
+        id: stale-check
+        run: |
+          # Get current major version from package.json (e.g., 3.0.0-rc.2 -> 3)
+          CURRENT_MAJOR=$(node -p "require('./package.json').version.split('.')[0]")
+          echo "Current major version: $CURRENT_MAJOR"
+
+          STALE_FOUND=""
+          for v in $(seq 1 $((CURRENT_MAJOR - 1))); do
+            # Search docs/ for /schemas/v{old}/ references, excluding release-notes
+            MATCHES=$(grep -rn "schemas/v${v}/" docs/ --include='*.md' --include='*.mdx' | grep -v 'docs/reference/release-notes' || true)
+            if [ -n "$MATCHES" ]; then
+              STALE_FOUND="$STALE_FOUND\n$MATCHES"
+            fi
+          done
+
+          if [ -n "$STALE_FOUND" ]; then
+            echo "❌ Found stale schema version references in docs/ (current major version is v${CURRENT_MAJOR}):"
+            echo -e "$STALE_FOUND"
+            echo ""
+            echo "These should be updated to schemas/v${CURRENT_MAJOR}/"
+            echo "If these are intentional historical references, move them to docs/reference/release-notes.mdx"
+            exit 1
+          else
+            echo "✅ No stale schema version references found"
+          fi
+
       - name: Check schema links
         id: check
         env:

docs/building/integration/a2a-guide.mdx

@@ -406,7 +406,7 @@ During execution, interim status updates can include optional data in `status.me
 }
 ```
 
-**All status payloads use AdCP schemas**: Both final statuses (completed/failed) and interim statuses (working, input-required, submitted) have corresponding AdCP schemas referenced in [`async-response-data.json`](https://adcontextprotocol.org/schemas/v2/core/async-response-data.json). Note that interim status schemas are evolving and may change in future versions, so implementors may choose to handle them more loosely.
+**All status payloads use AdCP schemas**: Both final statuses (completed/failed) and interim statuses (working, input-required, submitted) have corresponding AdCP schemas referenced in [`async-response-data.json`](https://adcontextprotocol.org/schemas/v3/core/async-response-data.json). Note that interim status schemas are evolving and may change in future versions, so implementors may choose to handle them more loosely.
 
 ### A2A Webhook Payload Types
 
@@ -451,7 +451,7 @@ The `status.message.parts[].data` field in A2A webhooks uses status-specific sch
 | `input-required` | `[task]-async-response-input-required.json` | Requirements, approval data |
 | `submitted` | `[task]-async-response-submitted.json` | Acknowledgment (usually minimal) |
 
-Schema reference: [`async-response-data.json`](https://adcontextprotocol.org/schemas/v2/core/async-response-data.json)
+Schema reference: [`async-response-data.json`](https://adcontextprotocol.org/schemas/v3/core/async-response-data.json)
 
 ### Webhook Handler Example
 

docs/building/integration/mcp-guide.mdx

@@ -229,7 +229,7 @@ const refined = await session.call('get_products', {
 
 MCP doesn't define push notifications. AdCP fills this gap by specifying the webhook configuration (`pushNotificationConfig`) and payload format (`mcp-webhook-payload.json`). When you configure a webhook, the server will POST task updates to your URL instead of requiring you to poll.
 
-**Webhook Envelope:** [`mcp-webhook-payload.json`](https://adcontextprotocol.org/schemas/v2/core/mcp-webhook-payload.json)
+**Webhook Envelope:** [`mcp-webhook-payload.json`](https://adcontextprotocol.org/schemas/v3/core/mcp-webhook-payload.json)
 
 ##### Best Practice: URL-Based Routing
 
@@ -307,7 +307,7 @@ The `result` field contains the AdCP data payload. For `completed`/`failed` stat
 
 #### MCP Webhook Envelope Fields
 
-The [`mcp-webhook-payload.json`](https://adcontextprotocol.org/schemas/v2/core/mcp-webhook-payload.json) envelope includes:
+The [`mcp-webhook-payload.json`](https://adcontextprotocol.org/schemas/v3/core/mcp-webhook-payload.json) envelope includes:
 
 **Required fields:**
 - `task_id` — Unique task identifier for correlation
@@ -354,7 +354,7 @@ The `result` field in MCP webhooks uses status-specific schemas:
 | `input-required` | `[task]-async-response-input-required.json` | Requirements, approval data |
 | `submitted` | `[task]-async-response-submitted.json` | Acknowledgment (usually minimal) |
 
-Schema reference: [`async-response-data.json`](https://adcontextprotocol.org/schemas/v2/core/async-response-data.json)
+Schema reference: [`async-response-data.json`](https://adcontextprotocol.org/schemas/v3/core/async-response-data.json)
 
 #### Webhook Handler Example
 

docs/building/schemas-and-sdks.mdx

@@ -12,7 +12,7 @@ AdCP schemas are available from two sources:
 
 | Source | URL | Best For |
 |--------|-----|----------|
-| Website | `https://adcontextprotocol.org/schemas/v2/` | Runtime fetching, version aliases |
+| Website | `https://adcontextprotocol.org/schemas/v3/` | Runtime fetching, version aliases |
 | GitHub | `https://github.com/adcontextprotocol/adcp/tree/main/dist/schemas` | Offline access, CI/CD pipelines |
 
 Both sources contain identical schemas. The GitHub repository includes all released versions with bundled schemas committed directly to the codebase.
@@ -21,8 +21,8 @@ Both sources contain identical schemas. The GitHub repository includes all relea
 
 | Schema | URL |
 |--------|-----|
-| Product | `https://adcontextprotocol.org/schemas/v2/core/product.json` |
-| Media Buy | `https://adcontextprotocol.org/schemas/v2/core/media-buy.json` |
+| Product | `https://adcontextprotocol.org/schemas/v3/core/product.json` |
+| Media Buy | `https://adcontextprotocol.org/schemas/v3/core/media-buy.json` |
 | Creative Format | `https://adcontextprotocol.org/schemas/v3/core/format.json` |
 | Schema Registry | `https://adcontextprotocol.org/schemas/v3/index.json` |
 
@@ -113,7 +113,7 @@ AdCP uses semantic versioning. Choose the right path for your use case:
 | Path | Example | Best For |
 |------|---------|----------|
 | Exact version | `/schemas/2.5.3/` | Production, SDK generation |
-| Major version | `/schemas/v2/` | Development, documentation |
+| Major version | `/schemas/v3/` | Development, documentation |
 | Minor version | `/schemas/v2.5/` | Stable development (patch updates only) |
 
 ### Production (Recommended)
@@ -133,7 +133,7 @@ Use the major version alias to stay current with backward-compatible updates:
 
 ```javascript
 const schema = await fetch(
-  'https://adcontextprotocol.org/schemas/v2/core/product.json'
+  'https://adcontextprotocol.org/schemas/v3/core/product.json'
 );
 ```
 
@@ -207,13 +207,13 @@ All request/response task schemas are bundled:
 | `bundled/protocol/` | get-adcp-capabilities |
 | `bundled/core/` | tasks-get, tasks-list |
 
-See the [schema registry](https://adcontextprotocol.org/schemas/v2/index.json) for all available schemas.
+See the [schema registry](https://adcontextprotocol.org/schemas/v3/index.json) for all available schemas.
 
 ## Version Discovery
 
 ```bash
 # Get current version
-curl https://adcontextprotocol.org/schemas/v2/index.json | jq '.adcp_version'
+curl https://adcontextprotocol.org/schemas/v3/index.json | jq '.adcp_version'
 ```
 
 Check [Release Notes](/docs/reference/release-notes) for version history and migration guides.

docs/creative/asset-types.mdx

@@ -12,8 +12,8 @@ Standardizing asset types ensures consistency across formats and makes requireme
 ## Important: Payload vs Requirements
 
 For payload schemas (the structure of the actual asset data supplied in creative manifests), see:
-- [Asset Type Registry](https://adcontextprotocol.org/schemas/v2/creative/asset-types/index.json) - Links to all payload schemas
-- Core Asset Schemas at `/schemas/v2/core/assets/` - Individual asset payload definitions
+- [Asset Type Registry](https://adcontextprotocol.org/schemas/v3/creative/asset-types/index.json) - Links to all payload schemas
+- Core Asset Schemas at `/schemas/v3/core/assets/` - Individual asset payload definitions
 
 **Key distinction:**
 

docs/creative/creative-manifests.mdx

@@ -318,7 +318,7 @@ When a creative agent receives a manifest for validation:
    - Look up the `asset_id` in `format.assets`
    - If not found → **reject** with error "Unknown asset_id 'banner_imag' not defined in format"
    - If found → determine the expected `asset_type` from the format requirement
-   - Fetch the asset type schema (e.g., `/schemas/v2/core/assets/image-asset.json`)
+   - Fetch the asset type schema (e.g., `/schemas/v3/core/assets/image-asset.json`)
    - Validate the asset payload against that schema
    - Validate the asset meets any additional constraints in the format's `requirements` field
 4. **Check all required assets are present** (where `required: true` in format spec)
@@ -446,9 +446,9 @@ For carousel, slideshow, and multi-asset formats, see the [Carousel & Multi-Asse
 
 ## Schema Reference
 
-- [Creative Manifest Schema](https://adcontextprotocol.org/schemas/v2/core/creative-manifest.json)
-- [Preview Creative Request](https://adcontextprotocol.org/schemas/v2/creative/preview-creative-request.json)
-- [Preview Creative Response](https://adcontextprotocol.org/schemas/v2/creative/preview-creative-response.json)
+- [Creative Manifest Schema](https://adcontextprotocol.org/schemas/v3/core/creative-manifest.json)
+- [Preview Creative Request](https://adcontextprotocol.org/schemas/v3/creative/preview-creative-request.json)
+- [Preview Creative Response](https://adcontextprotocol.org/schemas/v3/creative/preview-creative-response.json)
 
 ## Related Documentation
 

docs/creative/formats.mdx

@@ -61,7 +61,7 @@ Formats may be sourced from:
 
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/creative/list-creative-formats-response.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/creative/list-creative-formats-response.json",
   "formats": [
     {
       "format_id": {
@@ -90,7 +90,7 @@ Each format includes an `agent_url` that identifies the authoritative creative a
 
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
   "format_id": {
     "agent_url": "https://creative.adcontextprotocol.org",
     "id": "video_30s_hosted"
@@ -127,7 +127,7 @@ This approach allows publishers to present complex formats without constraining
 **Example**:
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
   "format_id": {
     "agent_url": "https://publisher.com",
     "id": "homepage_takeover_premium"
@@ -149,7 +149,7 @@ AdCP uses structured format identifiers everywhere to avoid ambiguity and namesp
 
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format-id.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format-id.json",
   "agent_url": "https://creative.adcontextprotocol.org",
   "id": "display_300x250"
 }
@@ -220,7 +220,7 @@ Formats are JSON objects with the following key fields:
 
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
   "format_id": {
     "agent_url": "https://creative.adcontextprotocol.org",
     "id": "video_30s_hosted"
@@ -440,7 +440,7 @@ Formats specify their rendered outputs via the `renders` array. Most formats pro
 
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
   "format_id": {
     "agent_url": "https://creative.adcontextprotocol.org",
     "id": "display_300x250"
@@ -466,7 +466,7 @@ Formats specify their rendered outputs via the `renders` array. Most formats pro
 **Multi-render example (companion ad):**
 ```json
 {
-  "$schema": "https://adcontextprotocol.org/schemas/v2/core/format.json",
+  "$schema": "https://adcontextprotocol.org/schemas/v3/core/format.json",
   "format_id": {
     "agent_url": "https://creative.adcontextprotocol.org",
     "id": "video_with_companion_300x250"

docs/creative/specification.mdx

@@ -373,11 +373,11 @@ Some creative protocol schemas (`build_creative`, `list_creative_formats`, `prev
 
 | Schema | Description |
 |--------|-------------|
-| [`core/format.json`](https://adcontextprotocol.org/schemas/v2/core/format.json) | Format definition |
-| [`core/creative-manifest.json`](https://adcontextprotocol.org/schemas/v2/core/creative-manifest.json) | Creative manifest |
-| [`core/creative-asset.json`](https://adcontextprotocol.org/schemas/v2/core/creative-asset.json) | Asset definition |
-| [`media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/v2/media-buy/list-creative-formats-request.json) | list_creative_formats request |
-| [`media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/v2/media-buy/list-creative-formats-response.json) | list_creative_formats response |
+| [`core/format.json`](https://adcontextprotocol.org/schemas/v3/core/format.json) | Format definition |
+| [`core/creative-manifest.json`](https://adcontextprotocol.org/schemas/v3/core/creative-manifest.json) | Creative manifest |
+| [`core/creative-asset.json`](https://adcontextprotocol.org/schemas/v3/core/creative-asset.json) | Asset definition |
+| [`media-buy/list-creative-formats-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/list-creative-formats-request.json) | list_creative_formats request |
+| [`media-buy/list-creative-formats-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/list-creative-formats-response.json) | list_creative_formats response |
 | [`creative/list-creatives-request.json`](https://adcontextprotocol.org/schemas/latest/creative/list-creatives-request.json) | list_creatives request |
 | [`creative/list-creatives-response.json`](https://adcontextprotocol.org/schemas/latest/creative/list-creatives-response.json) | list_creatives response |
 | [`creative/sync-creatives-request.json`](https://adcontextprotocol.org/schemas/latest/creative/sync-creatives-request.json) | sync_creatives request |