spec(creative): reconcile VAST version requirements and compatibility resolution

[bokelley]

Problem

AdCP 3.2 beta currently has contradictory VAST-version contracts:

• formats/canonical/video_vast.json defines singular params.vast_version.
• docs/creative/channels/video.mdx shows plural
  params.vast_versions: ["3.0", "4.0", "4.1", "4.2"].
• The same video documentation later says format requirements use singular
  vast_version and requires document, asset, format, and seller capability to
  match.
• get_adcp_capabilities.execution.creative_specs.vast_versions is plural and
  seller-wide.
• A VAST asset correctly declares one exact vast_version.

Because canonical format schemas are permissive, the plural documentation
example can validate while the schema silently ignores the field. An
implementation following the schema can expose only one accepted version per
format option; an implementation following the docs can expose an unenforced
list. This prevents interoperable version resolution.

References:

• video_vast.json
• video.mdx
• vast-asset.json
• vast-version.json

Proposed resolution

Use different cardinality at the two layers:

• Asset: singular vast_version — the exact version the supplied VAST URL
  or inline document declares.
• Product format option: plural vast_versions[] — the accepted set for
  that product/player/execution path.
• Agent capabilities: plural vast_versions[] — the seller-wide ceiling,
  never sufficient by itself to prove one product accepts every version.

Deprecate singular format-option vast_version as a one-element alias if
needed for 3.x compatibility. Do not relabel or synthesize an asset at a newer
version merely because the destination supports it.

Normative compatibility rule

A VAST asset is version-compatible only when:

asset.vast_version
  ∈ product.format_option.params.vast_versions
  ∩ seller.execution.creative_specs.vast_versions

When a pre-binding creative has multiple VAST source variants, candidate
versions are intersected with those two accepted sets. The buyer selects one,
or a seller with an explicit deterministic-resolution capability returns the
selected version. Highest-compatible is a useful default only after the
intersection is known.

VAST_VERSION_MISMATCH should report:

• the asset's declared version;
• the product-accepted versions;
• the seller-wide versions; and
• the selected format option.

Version roster

The single enum source remains authoritative: 2.0, 3.0, 4.0, 4.1, 4.2, and
4.3 in the current 3.2 beta. Product and capability arrays must reference it
rather than restating version strings or ranges.

Acceptance criteria

• Schema, documentation, examples, SDK types, and validation prose agree on
  singular asset version vs. plural accepted versions.
• Product format options can declare more than one accepted version without
  sibling-option duplication.
• The compatibility intersection is normative and tested.
• VAST_VERSION_MISMATCH returns all three relevant version sets/values.
• Examples cover a seller whose platform ceiling is 4.2 but one product
  accepts only 3.0/4.0.
• Conformance vectors include 4.3 and reject unsupported/relabelled assets.

Compatibility

Additive with a deprecated singular alias; otherwise changing the format param
name needs explicit 3.x migration handling.

[bokelley]

Triage

Classification: RFC
Bucket(s): spec / protocol, creative
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Contradiction confirmed as real interop blocker across four files (video_vast.json, video.mdx example, video.mdx normative text, v1-canonical-mapping.json). Dual-cardinality matches OpenRTB protocols[] pattern. Adding vast_versions[] is non-breaking given additionalProperties: true. Critical underspecification: WG must add a MUST clause that a format option's vast_versions ∩ seller.vast_versions must be non-empty. VAST_VERSION_MISMATCH extension is additive if supported_versions is retained. Verdict: non-breaking normative addition; needs WG before 3.2 GA.
• adtech-product-expert: Every SSP expresses plural accepted-version sets (OpenRTB protocols[] is an integer array in practice). Singular format field forces catalog explosion — one sibling option per version for the same inventory. "Highest-compatible" default needs normative tie-breaking or explicit "implementation-defined" designation. Verdict: real operator pain; must fix before GA.
• ad-tech-protocol-expert-deep: Three distinct concepts are currently conflated (confirmed). Intersection formula has four underspecified edge cases (see open normative points below). Current docs already show the plural wire shape; rolling back to singular would be a normative regression. Notes coupling with PR feat(creative): add CTV experience profiles for AdCP 3.2 #6591 — nonlinear CTV formats paired with multi-version accepted sets are the motivating use case.

My take: Expert panel converges. The schema/docs four-way inconsistency is live in 3.2 beta and will produce divergent version-matching logic now. Decision memo below for WG ratification.

---

Decision Memo — Normative class (awaits WG ratification)

Ruling (proposed): video_vast format options express their accepted VAST version set as a plural array vast_versions[]; the singular vast_version is retained as a deprecated one-element alias during the 3.x migration window; asset-layer vast_version is unchanged; a normative intersection rule governs compatibility.

Option A — Keep singular; require sibling format options per version

Each format option expresses exactly one accepted VAST version. A seller accepting VAST 3.0, 4.0, 4.1, and 4.2 publishes four sibling options:

[
  { "format_option_id": "preroll_v30", "format_kind": "video_vast",
    "params": { "vast_version": "3.0", "duration_ms_range": [15000, 30000] } },
  { "format_option_id": "preroll_v40", "format_kind": "video_vast",
    "params": { "vast_version": "4.0", "duration_ms_range": [15000, 30000] } }
]

Minimal schema change; docs must be corrected to remove the existing plural example (rolling back a 3.2 beta doc already visible to adopters).

Option B — Introduce vast_versions[] on format option; keep vast_version as deprecated alias (RFC proposal; experts lean this way)

One format option expresses the full accepted set. During the migration window a seller emits both fields; vast_versions is authoritative when present:

{
  "format_option_id": "preroll_vast",
  "format_kind": "video_vast",
  "params": {
    "vast_versions": ["3.0", "4.0", "4.1", "4.2"],
    "vast_version": "3.0",
    "duration_ms_range": [15000, 30000],
    "max_wrapper_depth": 3
  }
}

Schema change: add vast_versions array property to video_vast.json; add deprecation note to vast_version. Docs already reflect this shape — Option B is additive, not a regression. Strongly motivated by PR #6591: nonlinear CTV format options need to accept multiple VAST versions without sibling-option duplication.

Normative compatibility rule (either option):

asset.vast_version ∈ format.vast_versions ∩ seller.execution.creative_specs.vast_versions

VAST_VERSION_MISMATCH error.details MUST include:
  asset_version, format_versions, seller_versions, format_option_id
  (retain supported_versions = intersection value for backward compat)

Open normative points for the implementing PR (not WG blockers):

1. Seller MUST NOT publish a format option whose vast_versions ∩ seller.vast_versions is empty.
2. Absent seller.creative_specs.vast_versions → treat as full enum (permissive default, consistent with vast_validation pattern).
3. Format option with only vast_version present → treat as vast_versions: [vast_version].
4. Wrapper assets: outermost document's <VAST version> attribute is the authoritative declared version.
5. "Highest-compatible" selection when a pre-binding creative carries multiple source variants: define normative ordering (enum-index ascending) or designate "implementation-defined, not conformance-tested."
6. Merge coordination with PR feat(creative): add CTV experience profiles for AdCP 3.2 #6591: nonlinear CTV format options are the motivating multi-version use case; the two PRs should acknowledge the ordering dependency.

Class: normative | Dissent: none from expert panel | Refs: #6763

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01HsiQpnb2QF5nbJqdKii6vb

---

Generated by Claude Code