RFC: declare macro dialect, substitution owner, and encoding for creative tags

[bokelley]

Problem

AdCP can transport macro-bearing creative URLs, but cannot currently establish
whether they will work at the destination:

• url-asset.json accepts AdCP universal macros in URI templates.
• vast-asset.json also accepts VAST [MACRO] and ad-server ${MACRO} tokens.
• The 3.2 video contract explicitly treats unresolved macros as opaque and says
  macro correctness and substitution verification are out of scope.
• Real third-party tags mix vendor dialects from CM360, GAM, DV360, The Trade
  Desk, Amazon, Microsoft/Xandr, Adobe, Adform, Yahoo, Innovid/Flashtalking,
  verification vendors, and IAB VAST.

The same semantic has different spellings across platforms; the same-looking
token can have different scope; click URLs require different encoding depths;
and some values are owned by the buyer, seller, publisher player, or source ad
server. Preserving tokens is necessary but not sufficient: neither party can
determine preflight compatibility or explain which token remains unresolved.

Related: #6207 defines product tracking capabilities and substituted universal
macros for tracker assets. This issue covers creative delivery assets and
vendor/VAST dialects, not only tracker assets.

References:

• url-asset.json
• vast-asset.json
• video.mdx VAST validation
• IAB VAST live macro registry

Proposed direction

Add a macro contract usable by URL-delivered display tags, inline tag markup,
VAST URLs, and tracker assets. It should separate the literal source token from
its canonical meaning and resolver:

{
  "token": "%%TTD_CLK_ESC2%%",
  "dialect": "the_trade_desk",
  "semantic": "click_redirect",
  "resolved_by": "seller",
  "encoding": { "kind": "url", "depth": 2 },
  "required": true
}

Candidate fields/semantics:

• token: exact byte-preserved expression from the source.
• dialect: IAB/AdCP or vendor namespace; no semantic inference from spelling
  alone.
• semantic: reference to the universal macro vocabulary when verified, or
  unresolved/vendor-defined when not.
• resolved_by: buyer, seller, publisher/player, source ad server, or already
  resolved.
• encoding/value-shape constraints, including nested URL-encoding depth.
• required vs. optional and safe behavior when the value is unavailable.

Seller/product format options should advertise which macro dialects and
canonical semantics they can resolve. Creative validation should return a
structured result per token: resolved, preserved for a downstream resolver,
unsupported, or ambiguous.

Safety and interoperability rules

• Never replace a token from spelling alone when dialect/context is unknown.
• Never invent consent strings, vendor IDs, device IDs, or impression IDs.
• Preserve the original creative bytes and token list through pre-binding
  storage and variant selection.
• Click-macro encoding depth is part of the contract, not a string-replacement
  implementation detail.
• IAB's live VAST macro registry should be referenced/versioned rather than
  copied into an AdCP enum that will drift.
• Vendor-specific mappings require a cited vendor source and remain extensions
  until promoted into a governed shared semantic.

Acceptance criteria

• Creative assets can declare exact source tokens, dialect, semantic,
  resolver, and encoding requirements.
• Seller/product capabilities declare resolvable macro semantics/dialects.
• Validation returns per-token compatibility and actionable failures.
• Unknown or ambiguous tokens survive unchanged and never receive guessed
  replacements.
• Worked examples cover cache busting, click redirect with nested encoding,
  GDPR/TCF, GPP, player/VAST macros, and an unresolved vendor token.
• The contract composes with RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207 rather than defining a competing tracker
  capability model.
• Compliance tests cover preservation, substitution ownership, and encoding
  depth.

Compatibility

Additive. Existing opaque-token behavior remains the fallback when no macro
contract is supplied; absence means undeclared, not supported.

[bokelley]

Triage

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

What the experts said:

• ad-tech-protocol-expert: Wire shape is non-breaking and schema-coherent (both target schemas use additionalProperties: true); resolved_by: "seller" on vendor-dialect macros misrepresents where substitution actually happens in real tag chains; dialect as an open string risks silent spelling divergence across implementations; the validation response surface (per-token resolved/preserved/unsupported/ambiguous) has no schema home; and the normative boundary with RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207 is undrawn — when dialect: "adcp" and resolved_by: "seller" appear on a creative delivery asset it is unclear which RFC governs.
• adtech-product-expert: Problem is real — vendor macro fragmentation is the primary cause of broken click tracking and misfiring impression pixels in third-party tag campaigns; required: true and encoding depth as a first-class field are the right calls; IAB VAST registry reference is correct hygiene for video, but display and native macro vocabularies have no equivalent registry and the RFC scope for them is unclear; resolved_by taxonomy needs a third_party_ad_server node (CM360, Flashtalking resolve server-to-server before reaching the exchange — they are not buyer, seller, publisher, or player); dialect capability versioning is unspecified and stale dialect claims will produce correct-looking validation against outdated snapshots.

My take: Both experts converge — direction is sound, wire shape is non-breaking, and the RFC correctly distinguishes creative-delivery scope from #6207's tracker-asset scope. Four WG design decisions must be resolved before schema work begins; assigning a joint editor to #6207 and #6764 is the prerequisite.

---

Decision memo — candidate for DR ratification

Ruling: RFC #6764 proposes a non-breaking macro_contract array on creative delivery assets; the direction and wire shape are WG-ready, pending resolution of four design questions before any schema can merge.

Class: normative, non-breaking additive (new optional array on existing schemas; no required-field, enum-value, or type changes)

Synthesis:

Adding macro_contract as an optional array to url-asset.json and vast-asset.json fits existing draft-07 patterns, is cleanly non-breaking, and complements rather than conflicts with #6207's tracking_capabilities.substituted_macros_in_trackers[] (product-level macro substitution declaration on tracker assets vs. asset-level per-token declaration on creative delivery assets). DR-0005 (substitution not wire-observable) is consistent: the declaration of which tokens exist and who resolves them IS wire-observable as part of the creative manifest; actual serve-time substitution is not.

Four items require WG resolution before schema work begins:

1. resolved_by taxonomy is incomplete. Vendor-dialect macros (CM360, Flashtalking) are resolved server-to-server by the originating ad server before the tag reaches the exchange — they are not buyer, seller, publisher, or player. A third_party_ad_server (or source_ad_server) value is required; without it, the RFC's own safety rule ("never substitute from spelling alone") will be violated in the most common third-party tag chains, where resolved_by: "seller" is factually wrong and will be set anyway because no better option exists.

2. dialect needs an interop anchor. An open string with no normative vocabulary or prefix convention means two independent implementations of "the_trade_desk" may use different spellings and silently fail to interoperate. The RFC should define either a first-class dialect enum with an extension prefix (e.g., ttd., cm360.) or a dialect_version field — both to guard against vendor dialects that change silently across releases.

3. Validation response surface has no schema home. Per-token status (resolved / preserved / unsupported / ambiguous) is new normative surface; which task carries it and what its schema definition looks like are unspecified and must be settled before the asset-level declaration has any operational meaning.

4. Normative boundary with RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207 must be drawn. Both RFCs touch macro resolution ownership and token description; divergent descriptor schemas will fragment implementer mental models immediately. The boundary must be explicit before either RFC merges: which properties are the single source of truth for a token descriptor type, and which schema $refs which.

Recommendation: WG ratify the direction; assign a joint editor to #6207 and #6764 to resolve the four items above; confirm whether display and native macro vocabularies (no IAB registry equivalent) require a separate scope statement or a separate extension entry point.

Dissent: None.

---

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

---

Generated by Claude Code