url-asset: require url_type (or shape-defining field) to disambiguate variants

[bokelley]

Problem

url-asset is ambiguous in practice. The schema (static/schemas/source/core/assets/url-asset.json) requires only asset_type and url; url_type is optional. As a result, a conformant asset can look like:

{ "asset_type": "url", "url": "https://..." }

…and a receiving agent cannot tell whether this is a clickthrough, a tracker pixel, a tracker script, or something else. There is no fallback rule in the spec.

Proposal

Require one of:

• url_type present (preferred — explicit), or
• a shape-defining field that implies intent (e.g., dimensions for a pixel)

The simplest fix: make url_type required on url-asset. Current optionality doesn't buy us meaningful flexibility and pushes disambiguation onto buyer heuristics.

Impact

Buyer-side: removes the "everyone's just guessing" failure mode.
Seller-side: one additional required field on an already-small asset shape.
Back-compat: existing agents emitting url_type continue to work; agents omitting it need to start including it (straightforward migration).

Source

Reported by Nastassia Fulconis (Scope3) in early 3.0 feedback, 2026-04-23.

[bokelley]

/triage

[bokelley]

Triage

Classification: Feature request — spec change
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Correct direction, but two blockers before enforcement tightens — "tracker" in channel docs is not a valid enum value (schema has tracker_pixel/tracker_script/clickthrough), and url-asset-type.json (3 mechanism values) and url-asset-requirements.role (6 semantic values) are unreconciled parallel vocabularies. Non-breaking 3.x path exists; required belongs in 4.0.
• adtech-product-expert: Making optional → required is a MAJOR breaking change under AdCP versioning; sellers following current docs were explicitly told "you only need to supply the url value." Forcing required on 3.0.0 conformant implementations needs a 4.0 target. Enum/role coherence gap is the real pre-work.

My take: The direction is right. Making url_type required is the correct destination but it's breaking (optional → required = MAJOR). More urgent: channel docs (display, audio, DOOH, carousels) already emit "url_type": "tracker" which isn't a valid enum value — that's a 3.0.x doc fix that unblocks enforcement later.

@bokelley, your call: 3.x cleanup now + 4.0 required, or skip to required in 4.0?

Option A — 3.x non-breaking (two PRs, no wire change):

PR 1 — fix enum drift across channel docs (patch):

- "url_type": "tracker"
+ "url_type": "tracker_pixel"

PR 2 — fallback semantics + SHOULD advisory (minor):

// url-asset.json — description addition
+ Receivers MUST treat a url-asset with absent url_type as tracker_pixel
+ unless the format asset_id or url-asset-requirements.role disambiguates.
+ Sellers SHOULD always include url_type on new assets.

Existing 3.0.0 sellers unaffected. Ambiguity defined; vocabulary coherence work (url_type vs role) can land in 3.1.

Option B — 4.0 required (breaking):

// url-asset.json
  "required": [
    "asset_type",
    "url",
+   "url_type"
  ]

Also requires reconciling url-asset-type.json (3 mechanism values) with url-asset-requirements.role (6 semantic values) before shipping — otherwise two vocabularies answer the same question with incompatible terms. All sellers omitting url_type today must update.

---

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

---

Generated by Claude Code

[nastassiafulconis]

yeah direction's right but a couple things before we lock required in:

the "absent url_type → tracker_pixel" fallback scares me a bit. if a seller meant clickthrough and just forgot the field, we'd fire the landing page as a pixel and nobody would know. that's worse than the current "buyer guesses" thing imo. would rather fall back to url-asset-requirements.role if the format declared one, and let receivers reject when there's neither.

also url_type and role aren't really the same vocab — url_type is mechanism (click / pixel / script tag), role is purpose (impression, click, viewability, 3P). so click_tracker + url_type: tracker_pixel is totally fine. we should just say that out loud, otherwise making url_type required in 4.0 ships a field whose relationship to role is still fuzzy.

what i'd do:

• 3.0.x patch: fix "tracker" → "tracker_pixel" in the channel docs (carousels/display/audio/dooh are all wrong rn)
• 3.1: SHOULD on url_type + role-based fallback + clarify the mechanism vs purpose thing
• 4.0: required

jumping straight to 4.0-required without the role reconciliation feels like we're just moving the ambiguity up a level.

[bokelley]

Step 1 of your rollout shipped: #3670 fixes the 10 "url_type": "tracker" → "tracker_pixel" occurrences across display, audio, carousels, and DOOH channel docs.

Steps 2 (3.1: SHOULD on url_type, fallback to url-asset-requirements.role when format declared one, clarify mechanism vs purpose) and 3 (4.0: required) still need PRs — agree those are the right sequence. The role reconciliation in step 2 is the load-bearing piece; without it, step 3 just relocates the ambiguity as you flagged.

Note: dist/docs/3.0.2/creative/channels/* still carries the old value (snapshot #3617 was taken before this fix). Holding off on patching the frozen snapshot for now; happy to backport if you'd rather the published 3.0.2 docs reflect the correction immediately.

[bokelley]

Step 2 opened: #3671 (3.1, minor changeset).

• Adds SHOULD on url_type in url-asset.json description.
• Defines the receiver fallback you proposed: when url_type is absent, fall back to url-asset-requirements.role (clickthrough/landing_page → clickthrough mechanism; *_tracker roles → tracker_pixel). When neither is present, receivers MAY reject rather than guess.
• Reframes url_type as mechanism and role as purpose explicitly in both schema descriptions, so click_tracker + tracker_pixel reads as obviously correct.
• Rewrites docs/creative/asset-types.mdx URL Asset section. The old text listed url_type values that weren't in the schema enum at all (impression_tracker/video_tracker/landing_page) and told sellers "you only need to supply the url value" — which is what produced the original ambiguity. New text uses the actual enum and the SHOULD + fallback rule.

Wire format unchanged. With this landed, step 3 (require url_type in 4.0) becomes a clean breaking-change PR scoped to the 4.0 milestone — no role-reconciliation work bundled in.