@adcp/sdk 13.0.1 → 13.0.3

package/dist/lib/schemas-data/3.1/core/product-format-declaration.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/product-format-declaration.json",
+  "$id": "/schemas/3.1.20/core/product-format-declaration.json",
   "title": "Product Format Declaration",
   "description": "Inline format declaration on a product. The `format_kind` discriminator names which canonical format the product narrows; `params` carries the canonical's parameter schema (slots, dimensions, durations, codecs, character limits, platform_extensions, etc.). Optional `format_option_id` (stable identifier for routing when a product's `format_options` contains multiple declarations sharing the same `format_kind`), optional `publisher_domain` (namespace for the format option when it comes from a publisher adagents.json catalog), `display_name` (seller-controlled human-readable label for dashboard and catalog UIs), and `applies_to_channels` (subset of the product's declared channels this declaration applies to — lets a multi-channel product carry distinct format_options per channel). Discriminated-union shape generates clean tagged unions in TypeScript and Pydantic codegen. Replaces v1's named-format pattern (where products referenced a separately-defined format file via compound `format_id`). v1 named formats remain supported through the deprecation cycle; v2 product-bound declarations are opt-in.\n\n**Closed-set semantics (normative).** `format_options[]` is the closed set of accepted formats for this product. Sellers MUST reject `create_media_buy` requests targeting any `format_kind` (or format option reference) not present in this list — typically with `UNSUPPORTED_FEATURE` or a seller-specific code; the rejection is structural, not negotiable. `seller_preference` modulates *within* the accepted set (a soft ranking hint between equally-acceptable options), it is NOT an enforcement axis. A product wanting to say 'this format is the only one that works' lists exactly that one entry in `format_options[]`; everything else falls outside the set and is rejected by the closed-set rule.\n\n**Format matching vs satisfaction (normative).** Legacy named formats MUST be normalized to canonical declarations before comparison; do not exact-match raw `(agent_url, id)` pairs once a `format_id` has been projected through `canonical`, `v1_format_ref`, or the canonical mapping registry. Equivalence matching can treat a legacy fixed-size display ID and `format_kind: \"image\"` with matching `width`/`height` as the same underlying shape. Product satisfaction is stricter and directional: when this declaration specifies fixed constraints such as `width`, `height`, `duration_ms_exact`, or `duration_ms_range`, a buyer request or creative manifest MUST declare and satisfy those constraints. A broad request with no dimensions or duration does not satisfy a fixed-size or fixed-duration product; a broad product MAY accept a more specific creative unless another product constraint excludes it. Duration precedence is `duration_ms_exact` > `duration_ms_range`. Range constraints use containment: a range-based request satisfies this declaration only when every value it permits falls within this declaration's accepted range; overlap alone is insufficient. An exact value satisfies a range when the exact value falls inside the accepted interval. For hosted audio/video, a null range endpoint is unbounded: [null, 60000] means up to 60s, and [15000, null] means at least 15s; [null, null] is invalid because at least one endpoint must be bounded.\n\n**Custom format_kind** (`format_kind: \"custom\"`): for adopter-defined shapes that don't fit the 12 canonicals (multi-placement takeover, roadblock, branded content, cross-screen sponsorship, sponsorship lockup, newsletter sponsorship, AR lens, playable, live event sponsorship). When `format_kind` is `custom`, the declaration MUST carry `format_shape` (recognized global pattern from the [format-shape vocabulary registry](/schemas/core/format-shape-vocabulary.json)) AND `format_schema` (URI+digest reference to a fetchable schema describing the actual `params` and `slots`). Buyer agents fetch the schema, validate manifests structurally, and reason about manifests without per-seller integration code. See [adcp#3666](https://github.com/adcontextprotocol/adcp/issues/3666) for the canonical promotion queue.",
   "type": "object",
@@ -28,7 +28,7 @@
     "applies_to_channels": {
       "type": "array",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/channels.json"
+        "$ref": "/schemas/3.1.20/enums/channels.json"
       },
       "uniqueItems": true,
       "description": "Optional subset of the parent product's `channels` to which this declaration applies. When omitted, the declaration applies to ALL channels declared on the product. Lets a multi-channel product (e.g., `channels: ['display', 'video']`) carry distinct format_options per channel — `format_options: [{format_kind: 'image', applies_to_channels: ['display']}, {format_kind: 'video_hosted', applies_to_channels: ['video']}]`. Buyers ship channel-appropriate manifests per `applies_to_channels`."
@@ -60,12 +60,12 @@
       "type": "array",
       "minItems": 1,
       "items": {
-        "$ref": "/schemas/3.1.15/core/format-id.json"
+        "$ref": "/schemas/3.1.20/core/format-id.json"
       },
       "description": "Authoritative v2 → v1 link, expressed as an array of one or more v1 `format_id` ({agent_url, id}) values. Each entry asserts that this canonical-formats declaration IS the same underlying format as the referenced v1 named format. Always an array (single-ref is `[{...}]`) so the multi-size case below has a clean wire shape — adopters surveyed in the SDK implementor review pushed for this over the lossy single-ref form.\n\nThe v2 declaration's `params` MUST narrow (be compatible with) each referenced v1 format's `requirements` — see the 'Narrows — formal definition' section in canonical-formats.mdx. SDKs comparing dual-emitted shapes (`Product.format_ids[]` ⊇ entries from `v1_format_ref` AND `Product.format_options[]` carrying this declaration) treat the link as the authoritative pairing and run the narrowing check between this declaration and EACH referenced v1 format file's `requirements`.\n\n**Multi-size fan-out (normative).** When the declaration carries `params.sizes: [{w,h}, ...]` (multi-size flexible slot), sellers SHOULD carry one `v1_format_ref[]` entry per size, each pointing at the per-size v1 named format in the AAO catalog. Example: a multi-size image declaration with `sizes: [300x250, 728x90, 970x250]` SHOULD carry `v1_format_ref: [{aao, display_300x250_image}, {aao, display_728x90_image}, {aao, display_970x250_image}]`. v1-only buyers then see the product on all three sizes via the `format_ids[]` dual-emission. When `v1_format_ref[]` count < `sizes[]` count, SDKs MUST emit `FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE` on the response `errors[]` (advisory, alongside the partial-coverage v1 emit — NOT in place of it). SDKs MAY (non-normative) fan out automatically by catalog lookup when `v1_format_ref[]` has length 1 and `sizes[]` has length N — opt-in, requires catalog access; sellers asserting refs is the source of truth.\n\nMutually exclusive with `canonical_formats_only: true` — a declaration can EITHER assert no v1 projection (`canonical_formats_only: true`) OR link to v1 named formats (`v1_format_ref[]`), never both. When neither is present, SDKs fall back to the resolution order in `v1-canonical-mapping.json` (seller's explicit `canonical` field on the v1 file → registry glob → structural match → fail-closed).\n\nThis is the v2-side authoritative replacement for the v1-side `canonical_parameters` field on `format.json` (which is deprecated for 3.1, removed at 4.0). Sellers SHOULD prefer authoring v2 declarations with `v1_format_ref[]` over mirroring the v2 shape onto v1 files via `canonical_parameters`; the directional link (v2 declaration → v1 identifiers) is the same fact without the parallel-shape drift surface.\n\n**AAO-hosted convention (normative).** For IAB-standard formats (image dimensions, VAST/DAAST tags, standard third-party tags, HTML5 banner bundles), sellers SHOULD point each `v1_format_ref[].agent_url` at the AAO-hosted canonical agent URL `https://creative.adcontextprotocol.org` and use the registry-published id (e.g., `display_300x250_image`, `video_vast_30s`, `audio_standard_30s`, `display_300x250_html`, `display_js`). This converges the v1-wire namespace: every seller's IAB MREC points at the same `{agent_url, id}` pair, so v1-only buyers' allowlists work uniformly. Without this convention, every publisher's 300x250 ships with a different `v1_format_ref` (theirs vs nytimes.example vs cnn.example vs …) and the v1 wire fragments into per-publisher namespaces — exactly what canonical-formats was designed to eliminate.\n\nFor platform-specific formats (Meta Reels, TikTok Spark, Snap Spotlight, etc.), each `v1_format_ref[].agent_url` SHOULD point at the platform's own agent_url when the platform has adopted AdCP and publishes its own `adagents.json` with `formats[]`. When the platform has NOT adopted AdCP, sellers SHOULD point at the AAO community-registry mirror — `https://creative.adcontextprotocol.org/translated/<platform>` + `id: <platform-format-name>` (e.g., `https://creative.adcontextprotocol.org/translated/meta` + `id: meta_reels`). This keeps the v1 namespace converged across all sellers selling that platform's inventory until the platform owns its own adagents.json.\n\n**Platform-adoption cutover (normative).** When a platform adopts AdCP and publishes its own adagents.json, sellers MUST update `v1_format_ref[].agent_url` to the platform's adopted agent_url in the same minor release as the AAO mirror entry's `superseded_by` field goes live (see `static/schemas/source/adagents.json#superseded_by`). The AAO mirror entry SHOULD continue serving for ≥1 minor release after `superseded_by` is set, returning an advisory 'superseded' marker so v1 buyer allowlists keyed on the mirror URL get an explicit signal rather than a silent break. **Identity-confusion note**: the mirror URL is *format-shape namespace*, NOT seller identity. Inventory authorization always flows from `authorized_agents[]` + publisher signing keys; a buyer matching `v1_format_ref[].agent_url` against an allowlist is matching format-shape provenance, not seller identity.\n\n**Mirror domain migration (3.1).** Earlier drafts used `https://mirror.adcontextprotocol.org/translated/<platform>`. As of this release, the convention is `https://creative.adcontextprotocol.org/translated/<platform>` — sibling content under the AAO catalog domain we already host. Adopters who hardcoded the earlier mirror URL MUST migrate to the new path; the canonical-formats.mdx migration section documents the move. No transitional redirect is currently published (the earlier subdomain was never provisioned).\n\nFor seller-bespoke formats (a publisher's `acme_homepage_takeover` that doesn't fit IAB conventions), each `v1_format_ref[].agent_url` is the seller's own agent_url and the id is seller-namespaced. These won't appear in `v1-canonical-mapping.json`'s registry; they're seller-asserted only."
     },
     "format_schema": {
-      "$ref": "/schemas/3.1.15/core/platform-extension-ref.json",
+      "$ref": "/schemas/3.1.20/core/platform-extension-ref.json",
       "description": "REQUIRED when `format_kind: \"custom\"`; otherwise MUST be absent. URI+digest reference to a fetchable schema describing this custom shape's actual `params` and `slots`. Same hosting model as `platform_extensions`: open-ecosystem publishers host the artifact at the canonical URI on their subdomain; closed-platform / walled-garden shapes resolve through the AAO mirror at `https://creative.adcontextprotocol.org/translated/...`. Buyer agents fetch by `uri@digest` (immutable per digest, aggressive caching, `Cache-Control: public, max-age=31536000, immutable`), validate `params` and `slots` against the fetched schema, and reason about manifests structurally — same mechanic as platform_extensions but at the format-structure level. Without `format_schema`, custom shapes would be opaque to buyer agents and the protocol would regress to per-seller integration code; that's why the schema is required, not optional.\n\n**Fetch contract (normative)** — `format_schema` is load-bearing for validation (unlike `platform_extensions`, which is informational on the *consumption* side). The *transport* rules below apply identically to BOTH fields — any SDK fetching a `platform-extension-ref.json` URI MUST apply this contract regardless of whether the field name is `format_schema` or `platform_extensions`. A shared SDK fetch path that drops to the weakest bar undermines `format_schema`'s hardening. The consumption distinction (load-bearing vs informational) is about *what the body means*; the transport distinction is `https`-and-allowlisted regardless.\n\n- **Transport**: `https` only. Buyers MUST reject `http://`, `file://`, `data:`, and any non-`https` scheme. The URI MUST resolve to a JSON document that is itself a valid JSON Schema (Draft 07 or 2020-12; producers MUST declare `$schema`).\n- **SSRF protection**: buyers MUST resolve the URI hostname and reject if any resolved address is in RFC 1918 private space (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`), loopback (`127.0.0.0/8`, `::1`), link-local (`169.254.0.0/16`, `fe80::/10`), CGNAT (`100.64.0.0/10`), or any RFC 6761 special-use name (`.local`, `.localhost`, `.internal`, `.test`, `.example`, `.invalid`). Cloud metadata endpoints (`169.254.169.254`, `metadata.google.internal`, `kubernetes.default.svc`) are explicitly forbidden — these are credential-leak primitives. Buyers MUST pin the connection to the resolved IP (or re-resolve and re-validate the allowlist per request) to defeat DNS rebinding.\n- **HTTP redirects**: MUST be disabled. If a follow is implemented at all, the redirect target MUST pass the same scheme + SSRF + allowlist checks; otherwise the fetch hard-fails. Open redirects on same-origin paths are otherwise a free SSRF primitive.\n- **Response size cap**: response body MUST be capped at 1 MiB. Enforce during streaming, not after full buffering. Over-cap hard-fails identically to digest mismatch.\n- **Timeout**: SDKs SHOULD apply a fetch timeout ≤5 seconds. Timeout SHOULD be treated identically to an HTTP 5xx response (transient — retry policy at the SDK's discretion; on persistent failure surface as unresolved and skip the declaration for this session).\n- **Digest verification**: SHA-256 of the response body MUST equal `digest`. **Digest mismatch is a hard fail** — the buyer MUST treat the format declaration as unresolvable and MUST NOT validate manifests against the mismatched body. A divergent digest is either a malicious substitution or producer error; either way, falling back to the un-verified body breaks the trust model. Digest format: `sha256:` prefix + 64 lowercase hex characters. Cache key is `uri@digest`; digest mismatch MUST NOT be cached as a negative result keyed on `uri` alone (defeats CDN-flap recovery), and MUST be distinguishable in telemetry from network 5xx / 404 (sustained mismatch is a substitution-attack signal, not a flap).\n- **Sandboxing of `$ref`**: fetched schemas MAY use `$ref`. Buyers MUST resolve `$ref` only to URIs that are (a) same-origin as the parent `format_schema.uri` after RFC 3986 §6 normalization (lowercase scheme + host, strip default port, normalize path dot-segments, no userinfo component), OR (b) hosted under the AAO catalog domain (`https://creative.adcontextprotocol.org/...`), OR (c) intra-document JSON Pointer refs (`#/...`) bounded to the parent document's parsed tree. Cross-origin `$ref` to arbitrary URIs MUST be rejected. `$ref: file://...` MUST be rejected unconditionally. Transitive `$ref` chains MUST be bounded at depth ≤8 AND `$ref` count ≤256 across the resolved tree (depth 8 with breadth 100 per level is 10^16 nodes — depth alone is not enough). Publishers SHOULD inline rather than $ref where possible.\n- **Schema-compile bounds (DoS protection)**: validators MUST bound CPU/memory on fetched schemas. Recommended: compiled-schema keyword count ≤10 000, `pattern` regexes evaluated with a non-backtracking engine (re2) OR under a per-pattern timeout, per-manifest validation budget ≤250 ms (exceeded budget → treat manifest as invalid, surface telemetry signal). Without these, a 'valid' schema with catastrophic regex backtracking or exponential `allOf`/`anyOf` expansion pins a CPU forever.\n- **Cache**: buyers cache fetched schemas by `uri@digest` and treat them as immutable (the same hosting contract as `platform_extensions`). On `404`, network partition, or persistent fetch failure, buyers SHOULD degrade gracefully (treat the declaration as unresolved, skip it for the current `get_products` response, surface via `errors[]` with the relevant code) rather than failing the entire session.\n- **Schema-not-valid handling**: if the fetched body parses as JSON but is not a valid JSON Schema, the buyer MUST treat the declaration as unresolvable (same as digest mismatch) and surface via `errors[]`. Validators MUST NOT attempt partial validation against an invalid schema.\n- **AAO catalog trust**: `https://creative.adcontextprotocol.org/*` is a single trust anchor in the same-origin allowlist; compromise of the catalog domain or its CA compromises every buyer agent. Catalog-served bodies MUST be digest-pinned identically to origin fetches (the digest is on the *parent* `format_schema.uri@digest`, not on the catalog response). Future hardening (signed bodies, transparency log) is tracked separately."
     }
   },
@@ -161,7 +161,7 @@
           "const": "image"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/image.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/image.json"
         }
       },
       "required": [
@@ -177,7 +177,7 @@
           "const": "html5"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/html5.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/html5.json"
         }
       },
       "required": [
@@ -193,7 +193,7 @@
           "const": "display_tag"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/display_tag.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/display_tag.json"
         }
       },
       "required": [
@@ -209,7 +209,7 @@
           "const": "image_carousel"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/image_carousel.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/image_carousel.json"
         }
       },
       "required": [
@@ -225,7 +225,7 @@
           "const": "video_hosted"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/video_hosted.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/video_hosted.json"
         }
       },
       "required": [
@@ -241,7 +241,7 @@
           "const": "video_vast"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/video_vast.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/video_vast.json"
         }
       },
       "required": [
@@ -257,7 +257,7 @@
           "const": "audio_hosted"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/audio_hosted.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/audio_hosted.json"
         }
       },
       "required": [
@@ -273,7 +273,7 @@
           "const": "audio_daast"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/audio_daast.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/audio_daast.json"
         }
       },
       "required": [
@@ -289,7 +289,7 @@
           "const": "sponsored_placement"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/sponsored_placement.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/sponsored_placement.json"
         }
       },
       "required": [
@@ -305,7 +305,7 @@
           "const": "native_in_feed"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/native_in_feed.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/native_in_feed.json"
         }
       },
       "required": [
@@ -321,7 +321,7 @@
           "const": "responsive_creative"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/responsive_creative.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/responsive_creative.json"
         }
       },
       "required": [
@@ -337,7 +337,7 @@
           "const": "agent_placement"
         },
         "params": {
-          "$ref": "/schemas/3.1.15/formats/canonical/agent_placement.json"
+          "$ref": "/schemas/3.1.20/formats/canonical/agent_placement.json"
         }
       },
       "required": [

package/dist/lib/schemas-data/3.1/core/product-signal-targeting-option.json

@@ -1,12 +1,12 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/product-signal-targeting-option.json",
+  "$id": "/schemas/3.1.20/core/product-signal-targeting-option.json",
   "title": "Product Signal Targeting Option",
   "description": "A signal the seller makes available inline for package-level signal composition on this product. Product.signal_targeting_options is used when the product needs product-scoped pricing, activation handles, defaults, grouping hints, a brief/refine-selected subset, or a curated inline menu. Wholesale products can instead omit inline options when the selectable menu is the broader get_signals feed. Product-local signals define their name and value_type inline through the shared signal-listing fields; data-provider and signal-source refs may omit those definition fields when the referenced definition or source is authoritative.",
   "type": "object",
   "allOf": [
     {
-      "$ref": "/schemas/3.1.15/core/signal-listing.json"
+      "$ref": "/schemas/3.1.20/core/signal-listing.json"
     },
     {
       "description": "Signals that require activation need an operational handle the buyer can pass to activate_signal before package selection.",
@@ -74,7 +74,7 @@
       "type": "array",
       "description": "Signal pricing options available when this signal is selected on this product. Product-scoped pricing is authoritative for this product; if get_signals exposes a different default rate card, use this product-scoped price when composing the buy. Buyers pass the selected pricing_option_id in packages[].targeting_overlay.signal_targeting_groups.groups[].signals[].pricing_option_id. Omit when the signal is bundled into the product price or has no incremental cost.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/vendor-pricing-option.json"
+        "$ref": "/schemas/3.1.20/core/vendor-pricing-option.json"
       },
       "minItems": 1
     }

package/dist/lib/schemas-data/3.1/core/product.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/product.json",
+  "$id": "/schemas/3.1.20/core/product.json",
   "title": "Product",
   "description": "Represents available advertising inventory",
   "type": "object",
@@ -24,7 +24,7 @@
       "items": {
         "allOf": [
           {
-            "$ref": "/schemas/3.1.15/core/publisher-property-selector.json"
+            "$ref": "/schemas/3.1.20/core/publisher-property-selector.json"
           },
           {
             "not": {
@@ -41,7 +41,7 @@
       "type": "array",
       "description": "Advertising channels this product is sold as. Products inherit from their properties' supported_channels but may narrow the scope. For example, a product covering YouTube properties might be sold as ['ctv'] even though those properties support ['olv', 'social', 'ctv'].",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/channels.json"
+        "$ref": "/schemas/3.1.20/enums/channels.json"
       },
       "uniqueItems": true
     },
@@ -49,7 +49,7 @@
       "type": "array",
       "description": "Legacy named-format path: array of supported creative format IDs (structured format_id objects with agent_url and id). Products MUST carry `format_ids`, `format_options`, or BOTH; at least one is required. Named formats predate 3.1 and remain supported through the deprecation calendar (2027-Q4 floor / 2029-Q1 ceiling).\n\n**Dual emission**: A product MAY carry both `format_ids` and `format_options` simultaneously during the migration window. This is the recommended seller pattern — author once, SDK projects to both wire shapes via the [canonical mapping registry](/schemas/registries/v1-canonical-mapping.json), every buyer reads what it knows. When both are present, the two MUST refer to the SAME underlying format declaration (the `format_options[i]` narrows the canonical that the named format in `format_ids[i]` resolves to via the registry / explicit `canonical` field). SDKs that derive both shapes from one source guarantee this invariant; SDKs that don't MUST treat divergence as a build error and refuse to emit. **Buyer rule**: when both are present, prefer `format_options`; treat `format_ids` as fallback for legacy-format buyers. **Non-projectable formats**: when a named format has no clean 3.1+ format-option projection (no registry entry, no explicit `canonical` declaration on the named format, no structural match), SDKs MUST NOT emit `format_options` for that product — only `format_ids` ships, and the product remains legacy-format-only until the seller adds an explicit `canonical` field or files a registry entry.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/format-id.json"
+        "$ref": "/schemas/3.1.20/core/format-id.json"
       }
     },
     "format_options": {
@@ -57,14 +57,14 @@
       "minItems": 1,
       "description": "3.1+ format-option path: one or more inline format declarations the product accepts. Each element narrows a canonical format with parameters, slots, and platform_extensions. The 90% case is a single-element array (one canonical narrowed for the product). Multi-element use cases: a product that accepts EITHER a third-party-hosted creative (for example, externally served `html5`) OR an internal `display_tag`; a video product that accepts a hosted `video_hosted` upload OR a `video_vast` tag. Buyers pick which option they're shipping at `sync_creatives` time by aligning their manifest to the matching declaration's `format_kind` and slots.\n\nProducts MUST carry `format_ids`, `format_options`, or BOTH; at least one is required. See `format_ids` description for the dual-emission contract (same underlying declaration when both are present; SDK derives one from the other; buyers prefer `format_options` when both are present).\n\nWhen `placements[]` also declare `format_ids` or `format_options`, product-level formats are the upper bound for the sellable product. Placement-level formats narrow the product-wide accepted set for that placement; they MUST NOT introduce a format the product does not accept. Buyers compute the effective accepted set for a placement as the intersection of product-level and placement-level declarations. For format options, match publisher-declared options by `{ publisher_domain, format_option_id }`, match product-local options by `format_option_id` when `publisher_domain` is omitted, and otherwise match declarations with the same `format_kind` whose placement parameters narrow the product declaration. If a placement has no format declaration, it inherits the product-level formats.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/product-format-declaration.json"
+        "$ref": "/schemas/3.1.20/core/product-format-declaration.json"
       }
     },
     "placements": {
       "type": "array",
       "description": "Optional array of specific public placements within this product. Placement IDs are scoped by publisher domain. Product placements declare `kind` to distinguish publisher-referenced placements (`publisher_ref`) from seller-defined inline placements (`seller_inline`). Publisher-referenced placements carry `publisher_domain` plus `placement_id` and may omit `name` because buyers resolve the name from the publisher's adagents.json placement declarations. Seller-inline placements carry buyer-facing `name` directly; when `publisher_domain` is omitted, buyers MAY interpret the placement ID relative to the seller agent's own publisher domain only during the legacy single-publisher transition. Community-maintained fallback files are resolver/source metadata, not a distinct placement kind. Each placement MUST declare `mode: 'targetable'` (buyer may select the placement by PlacementRef, for example in creative assignments) or `mode: 'included'` (part of the public product composition but not buyer-selectable). Placement-level format declarations narrow the product-level creative contract and MUST NOT broaden it. Seller-private delivery objects, source/origin details, and ad-server mappings MUST NOT be exposed here.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/placement.json"
+        "$ref": "/schemas/3.1.20/core/placement.json"
       },
       "minItems": 1
     },
@@ -72,7 +72,7 @@
       "type": "array",
       "description": "Declared video placement types that may be included in this product, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Use on OLV, CTV, and other video products when buyers need to distinguish instream, accompanying-content, interstitial, and standalone/no-content inventory. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `video_placement_types`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/video-placement-type.json"
+        "$ref": "/schemas/3.1.20/enums/video-placement-type.json"
       },
       "uniqueItems": true,
       "minItems": 1
@@ -81,7 +81,7 @@
       "type": "array",
       "description": "Declared audio distribution types that may be included in this product, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. Use on radio, streaming-audio, podcast, gaming, and other audio products when buyers need to distinguish music streaming services, FM/AM broadcast, podcasts, catch-up radio, web radio, video-game audio, and text-to-speech inventory without changing the buyer-facing channel or adagents.json property type. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `audio_distribution_types`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/audio-distribution-type.json"
+        "$ref": "/schemas/3.1.20/enums/audio-distribution-type.json"
       },
       "uniqueItems": true,
       "minItems": 1
@@ -90,7 +90,7 @@
       "type": "array",
       "description": "Declared sponsored-placement types that may be included in this product, distinguishing where catalog-driven retail-media placements render on the retailer surface (sponsored search, sponsored display, or sponsored native). Use on retail-media products when buyers need to distinguish search-keyed, display, and native in-grid sponsored inventory. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `sponsored_placement_types`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/sponsored-placement-type.json"
+        "$ref": "/schemas/3.1.20/enums/sponsored-placement-type.json"
       },
       "uniqueItems": true,
       "minItems": 1
@@ -99,32 +99,32 @@
       "type": "array",
       "description": "Declared social-placement surfaces that may be included in this product, distinguishing the in-app surface where social placements render (feed, stories, short_video, explore, or search). Use on social products when buyers need to distinguish feed, story, short-video, and discovery surfaces. Aggregate products and ad-network products MAY declare multiple values. When `placements[]` also carry `social_placement_surfaces`, this product-level array SHOULD be the union of the placement-level declarations the seller may deliver under the product. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/social-placement-surface.json"
+        "$ref": "/schemas/3.1.20/enums/social-placement-surface.json"
       },
       "uniqueItems": true,
       "minItems": 1
     },
     "delivery_type": {
-      "$ref": "/schemas/3.1.15/enums/delivery-type.json"
+      "$ref": "/schemas/3.1.20/enums/delivery-type.json"
     },
     "exclusivity": {
-      "$ref": "/schemas/3.1.15/enums/exclusivity.json",
+      "$ref": "/schemas/3.1.20/enums/exclusivity.json",
       "description": "Whether this product offers exclusive access to its inventory. Defaults to 'none' when absent. Most relevant for guaranteed products tied to specific collections or placements."
     },
     "pricing_options": {
       "type": "array",
       "description": "Available pricing models for this product",
       "items": {
-        "$ref": "/schemas/3.1.15/core/pricing-option.json"
+        "$ref": "/schemas/3.1.20/core/pricing-option.json"
       },
       "minItems": 1
     },
     "forecast": {
-      "$ref": "/schemas/3.1.15/core/delivery-forecast.json",
+      "$ref": "/schemas/3.1.20/core/delivery-forecast.json",
       "description": "Forecasted delivery metrics for this product. Gives buyers an estimate of expected performance before requesting a proposal."
     },
     "outcome_measurement": {
-      "$ref": "/schemas/3.1.15/core/outcome-measurement.json",
+      "$ref": "/schemas/3.1.20/core/outcome-measurement.json",
       "description": "**Deprecated as of this minor.** Outcome capabilities (incremental sales lift, brand lift, foot traffic, etc.) are now declared via `reporting_capabilities.available_metrics` (the same path used for impressions, conversions, ROAS) with `qualifier.attribution_methodology` and `qualifier.attribution_window` carrying the methodology and window on commit. New implementations SHOULD use the unified pattern; this field is retained for one-minor backwards compatibility and removed at the next major. See `outcome-measurement.json` description for migration guidance."
     },
     "delivery_measurement": {
@@ -135,7 +135,7 @@
           "type": "array",
           "description": "Measurement vendors used for this product, as structured `BrandRef` identities. Multiple entries when multiple vendors play different roles (e.g., the ad server plus a separate viewability vendor like IAS or DV; or a retail-media seller plus a third-party retail measurement vendor like Circana or NielsenIQ). Each vendor's `brand.json` `agents[type='measurement']` is the discovery anchor; metric definitions live on the agent's `get_adcp_capabilities.measurement.metrics[]` block. Distinct from `performance_standards[].vendor` which carries vendor identity for *committed* metrics with thresholds — this field carries vendor identity for the overall measurement story, including non-committed-but-reported metrics.",
           "items": {
-            "$ref": "/schemas/3.1.15/core/brand-ref.json"
+            "$ref": "/schemas/3.1.20/core/brand-ref.json"
           },
           "minItems": 1
         },
@@ -150,35 +150,35 @@
       }
     },
     "measurement_terms": {
-      "$ref": "/schemas/3.1.15/core/measurement-terms.json",
+      "$ref": "/schemas/3.1.20/core/measurement-terms.json",
       "description": "Seller's default billing measurement and makegood terms. Declares who counts the billing metric and what remedies apply when thresholds are breached. Buyers may propose different terms at media buy creation — sellers accept, reject (TERMS_REJECTED), or adjust per their policy."
     },
     "performance_standards": {
       "type": "array",
       "description": "Seller's default performance standards for this product: viewability, IVT, completion rate, brand safety, attention score. Buyers may propose different standards at media buy creation. When absent, no structured performance standards apply.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/performance-standard.json"
+        "$ref": "/schemas/3.1.20/core/performance-standard.json"
       },
       "minItems": 1
     },
     "cancellation_policy": {
-      "$ref": "/schemas/3.1.15/core/cancellation-policy.json",
+      "$ref": "/schemas/3.1.20/core/cancellation-policy.json",
       "description": "Cancellation terms for this product. Declares the minimum notice period required before cancellation takes effect and any penalties for insufficient notice. Relevant for guaranteed delivery products. Buyers accept these terms by creating a media buy against the product."
     },
     "allowed_actions": {
       "type": "array",
       "description": "Actions buyers may perform on buys created against this product, scoped to statuses and modes. Advisory template — the authoritative per-buy capability is `available_actions[]` on the buy response, which resolves modes against current buy state, account tier, and negotiated terms. Buyers SHOULD use this for pre-flight product selection (\"which products let me self-serve cancel within 72hr?\") and read `available_actions[]` for runtime decisions. The array is uniquely keyed by `action` — sellers MUST NOT emit two entries with the same `action` value. Absence means the seller has not declared a structured action surface for this product — buyers fall back to `valid_actions[]` on buy responses for the flat string vocabulary.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/product-allowed-action.json"
+        "$ref": "/schemas/3.1.20/core/product-allowed-action.json"
       },
       "minItems": 1,
       "uniqueItems": true
     },
     "reporting_capabilities": {
-      "$ref": "/schemas/3.1.15/core/reporting-capabilities.json"
+      "$ref": "/schemas/3.1.20/core/reporting-capabilities.json"
     },
     "creative_policy": {
-      "$ref": "/schemas/3.1.15/core/creative-policy.json"
+      "$ref": "/schemas/3.1.20/core/creative-policy.json"
     },
     "is_custom": {
       "type": "boolean",
@@ -194,14 +194,14 @@
       "description": "Deprecated. Legacy/non-selectable metadata for data-provider signals already bundled into or associated with this product. This field does not provide buyer-selectable options, prices, or seller activation handles. Use included_signals for non-selectable product signal metadata, or signal_targeting_options for selectable package-level signal groups.",
       "deprecated": true,
       "items": {
-        "$ref": "/schemas/3.1.15/core/data-provider-signal-selector.json"
+        "$ref": "/schemas/3.1.20/core/data-provider-signal-selector.json"
       }
     },
     "included_signals": {
       "type": "array",
       "description": "Non-selectable signal metadata for signals already included in, bundled with, or planned into this product. These signals describe what the product is; buyers do not select them in packages[].targeting_overlay.signal_targeting_groups and this field does not imply package-level signal targeting. Use signal_ref scope 'data_provider' or 'signal_source' to reference externally defined signals without redefining their name or value_type. Use signal_ref scope 'product' with name and value_type when the included signal is defined only by this product.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/signal-listing.json"
+        "$ref": "/schemas/3.1.20/core/signal-listing.json"
       },
       "minItems": 1
     },
@@ -209,12 +209,12 @@
       "type": "array",
       "description": "Inline seller-offered signals that may be applied to packages for this product at create_media_buy time. Each entry references a named signal definition with signal_ref scope 'product' for a product-local signal option, scope 'data_provider' for an external signal definition published in adagents.json signals[] that the seller is authorized to apply, or scope 'signal_source' for a source-native signal. Product-local options define name and value_type inline; data-provider and signal-source options may omit those fields when the referenced definition or source is authoritative. Use this field when the selectable menu is product-specific, has product-specific pricing or activation handles, is the relevant subset for a brief/refine result, or should be rendered without an additional get_signals call. Wholesale products may omit this field and rely on get_signals for the selectable signal feed. Buyers select eligible signals through packages[].targeting_overlay.signal_targeting_groups when signal_targeting_rules allow; fixed/default entries are applied by the seller and echoed on the package state. Sellers MUST set signal_targeting_allowed to true whenever this field is present. Bundled, non-selectable signal metadata belongs in included_signals; legacy data_provider_signals may appear only for backwards compatibility.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/product-signal-targeting-option.json"
+        "$ref": "/schemas/3.1.20/core/product-signal-targeting-option.json"
       },
       "minItems": 1
     },
     "signal_targeting_rules": {
-      "$ref": "/schemas/3.1.15/core/signal-targeting-rules.json",
+      "$ref": "/schemas/3.1.20/core/signal-targeting-rules.json",
       "description": "Composition rules for selecting signals on this product. The selectable signal menu may come from inline signal_targeting_options or from get_signals when a wholesale product omits inline options. This is product-scoped because products may be backed by different ad servers with different Boolean targeting support and group limits."
     },
     "signal_targeting_allowed": {
@@ -226,7 +226,7 @@
       "type": "array",
       "description": "Catalog types this product supports for catalog-driven campaigns. A sponsored product listing declares [\"product\"], a job board declares [\"job\", \"offering\"]. Buyers match synced catalogs to products via this field.",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/catalog-type.json"
+        "$ref": "/schemas/3.1.20/enums/catalog-type.json"
       },
       "uniqueItems": true,
       "minItems": 1
@@ -260,7 +260,7 @@
           "type": "array",
           "description": "Reach units this product can optimize for. Required when supported_metrics includes 'reach'. Buyers must set reach_unit to a value in this list on reach optimization goals — sellers reject unsupported values.",
           "items": {
-            "$ref": "/schemas/3.1.15/enums/reach-unit.json"
+            "$ref": "/schemas/3.1.20/enums/reach-unit.json"
           },
           "minItems": 1
         },
@@ -290,7 +290,7 @@
       "additionalProperties": true
     },
     "vendor_metric_optimization": {
-      "$ref": "/schemas/3.1.15/core/vendor-metric-optimization.json",
+      "$ref": "/schemas/3.1.20/core/vendor-metric-optimization.json",
       "description": "Vendor-attested metric optimization capabilities for this product. Presence indicates the product supports `optimization_goals` with `kind: 'vendor_metric'` — the seller's bidding stack can steer delivery toward a specific vendor's measurement (e.g., DV/IAS/Adelaide attention, Scope3 emissions, Kantar brand lift, retail-media partner metrics). Distinct from `metric_optimization` (seller-native metrics with no vendor binding) and from `reporting_capabilities.vendor_metrics` (which declares what the product can *report* rather than what it can *optimize against*). A product may report a vendor metric without being able to optimize for it. Buyers MUST verify the goal's `(vendor, metric_id)` is in `supported_metrics` AND that the package's `committed_metrics[]` includes a matching `{ scope: 'vendor', vendor, metric_id }` entry — optimization without committed reporting is unverifiable and is rejected at the wire level."
     },
     "max_optimization_goals": {
@@ -299,7 +299,7 @@
       "description": "Maximum number of optimization_goals this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1 goal — buyers sending arrays longer than this value should expect the seller to use only the highest-priority (lowest priority number) goal."
     },
     "measurement_readiness": {
-      "$ref": "/schemas/3.1.15/core/measurement-readiness.json",
+      "$ref": "/schemas/3.1.20/core/measurement-readiness.json",
       "description": "Assessment of whether the buyer's event source setup is sufficient for this product to optimize effectively. Only present when the seller can evaluate the buyer's account context. Buyers should check this before creating media buys with event-based optimization goals."
     },
     "conversion_tracking": {
@@ -310,7 +310,7 @@
           "type": "array",
           "description": "Action sources relevant to this product (e.g. a retail media product might have 'in_store' and 'website', while a display product might only have 'website')",
           "items": {
-            "$ref": "/schemas/3.1.15/enums/action-source.json"
+            "$ref": "/schemas/3.1.20/enums/action-source.json"
           },
           "minItems": 1
         },
@@ -382,7 +382,7 @@
       "description": "Optional standard visual card for displaying this product in user interfaces (catalog browsers, dashboards, agent UIs). Distinct from `format` — product_card describes the UI rendering of the product itself, not the ad creative the product accepts. Typed inline; no format_id indirection. Receivers render the card directly from these fields.",
       "properties": {
         "image": {
-          "$ref": "/schemas/3.1.15/core/assets/image-asset.json",
+          "$ref": "/schemas/3.1.20/core/assets/image-asset.json",
           "description": "Hero image for the card. Recommended ~300x400 (4:3 portrait) for the standard card layout; receivers may scale."
         },
         "title": {
@@ -413,14 +413,14 @@
       "description": "Optional detailed card with hero + carousel + structured specifications, for rich product presentation (media-kit-style pages, full product detail views). Distinct from `format` — describes the UI rendering of the product itself, not the ad creative the product accepts. Typed inline; no format_id indirection.",
       "properties": {
         "hero_image": {
-          "$ref": "/schemas/3.1.15/core/assets/image-asset.json",
+          "$ref": "/schemas/3.1.20/core/assets/image-asset.json",
           "description": "Primary hero image at the top of the detailed view."
         },
         "carousel_images": {
           "type": "array",
           "description": "Additional images for a swipeable carousel below the hero.",
           "items": {
-            "$ref": "/schemas/3.1.15/core/assets/image-asset.json"
+            "$ref": "/schemas/3.1.20/core/assets/image-asset.json"
           }
         },
         "title": {
@@ -468,7 +468,7 @@
       "type": "array",
       "description": "Collections available in this product. Each entry references collections declared in an adagents.json by domain and collection ID. Buyers resolve full collection objects from the referenced adagents.json.",
       "items": {
-        "$ref": "/schemas/3.1.15/core/collection-selector.json"
+        "$ref": "/schemas/3.1.20/core/collection-selector.json"
       },
       "minItems": 1
     },
@@ -481,7 +481,7 @@
       "type": "array",
       "description": "Specific installments included in this product. Each installment references its parent collection via collection_id when the product spans multiple collections. When absent with collections present, the product covers the collections broadly (run-of-collection).",
       "items": {
-        "$ref": "/schemas/3.1.15/core/installment.json"
+        "$ref": "/schemas/3.1.20/core/installment.json"
       }
     },
     "enforced_policies": {
@@ -509,7 +509,7 @@
           "type": "array",
           "description": "What the publisher can accept back from context match.",
           "items": {
-            "$ref": "/schemas/3.1.15/enums/response-type.json"
+            "$ref": "/schemas/3.1.20/enums/response-type.json"
           },
           "minItems": 1,
           "default": [
@@ -555,7 +555,7 @@
                 "type": "array",
                 "description": "Identity types this regional provider can resolve. The router filters providers whose uid_types includes the request's uid_type. Required when identity_match is true.",
                 "items": {
-                  "$ref": "/schemas/3.1.15/enums/uid-type.json"
+                  "$ref": "/schemas/3.1.20/enums/uid-type.json"
                 },
                 "minItems": 1
               }
@@ -611,14 +611,14 @@
           "maxLength": 2000
         },
         "ext": {
-          "$ref": "/schemas/3.1.15/core/ext.json"
+          "$ref": "/schemas/3.1.20/core/ext.json"
         }
       },
       "minProperties": 1,
       "additionalProperties": true
     },
     "ext": {
-      "$ref": "/schemas/3.1.15/core/ext.json"
+      "$ref": "/schemas/3.1.20/core/ext.json"
     }
   },
   "required": [

package/dist/lib/schemas-data/3.1/core/property-id.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/property-id.json",
+  "$id": "/schemas/3.1.20/core/property-id.json",
   "title": "Property ID",
   "description": "Identifier for a publisher property. Must be lowercase alphanumeric with underscores only.",
   "type": "string",

package/dist/lib/schemas-data/3.1/core/property-list-ref.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/property-list-ref.json",
+  "$id": "/schemas/3.1.20/core/property-list-ref.json",
   "title": "Property List Reference",
   "description": "Reference to an externally managed property list. Enables passing large property sets (50,000+) without embedding them in requests. The receiving agent fetches and caches the list independently.",
   "type": "object",

package/dist/lib/schemas-data/3.1/core/property-tag.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/property-tag.json",
+  "$id": "/schemas/3.1.20/core/property-tag.json",
   "title": "Property Tag",
   "description": "Tag for categorizing publisher properties. Must be lowercase alphanumeric with underscores only.",
   "type": "string",

package/dist/lib/schemas-data/3.1/core/property.json

@@ -1,16 +1,16 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "/schemas/3.1.15/core/property.json",
+  "$id": "/schemas/3.1.20/core/property.json",
   "title": "Property",
   "description": "An advertising property that can be validated via adagents.json",
   "type": "object",
   "properties": {
     "property_id": {
-      "$ref": "/schemas/3.1.15/core/property-id.json",
+      "$ref": "/schemas/3.1.20/core/property-id.json",
       "description": "Unique identifier for this property (optional). Enables referencing properties by ID instead of repeating full objects."
     },
     "property_type": {
-      "$ref": "/schemas/3.1.15/enums/property-type.json",
+      "$ref": "/schemas/3.1.20/enums/property-type.json",
       "description": "Type of advertising property"
     },
     "name": {
@@ -24,7 +24,7 @@
         "type": "object",
         "properties": {
           "type": {
-            "$ref": "/schemas/3.1.15/enums/identifier-types.json",
+            "$ref": "/schemas/3.1.20/enums/identifier-types.json",
             "description": "Type of identifier for this property"
           },
           "value": {
@@ -44,7 +44,7 @@
       "type": "array",
       "description": "Tags for categorization and grouping (e.g., network membership, content categories)",
       "items": {
-        "$ref": "/schemas/3.1.15/core/property-tag.json"
+        "$ref": "/schemas/3.1.20/core/property-tag.json"
       },
       "uniqueItems": true
     },
@@ -52,7 +52,7 @@
       "type": "array",
       "description": "Advertising channels this property supports (e.g., ['display', 'olv', 'social']). Publishers declare which channels their inventory aligns with. Properties may support multiple channels. See the Media Channel Taxonomy for definitions.",
       "items": {
-        "$ref": "/schemas/3.1.15/enums/channels.json"
+        "$ref": "/schemas/3.1.20/enums/channels.json"
       },
       "uniqueItems": true
     },