RFC: capability-gated custom targeting keys

[bokelley]

Problem

AdCP has no first-class way for a buyer to send publisher-specific targeting keys, but adding an unbounded custom map without discovery would let buyers request keys a seller cannot interpret and let sellers silently ignore them.

Split from #4239. The typed device_platform_exclude slice is handled separately in #6166.

3.2 design target

Define a capability-gated custom-targeting contract:

• seller capabilities declare the accepted key namespace and, where enumerable, accepted values;
• targeting uses a Record<string, string[]> shape for set-membership intent;
• buyers send only declared keys;
• sellers MUST reject undeclared keys or unsupported values rather than silently dropping them;
• define key ownership/namespacing so two integrations cannot assign different meaning to the same key;
• do not reuse key_value_pairs (collides with signals/TMP concepts) or introduce first-class browser/media-type fields in this issue.

WG review shape

Bring this back as a short two-option memo:

1. finite enumeration: capabilities declare keys and all accepted values;
2. typed-open values: capabilities declare keys plus value constraints when full enumeration is impractical.

Both options retain reject-rather-than-drop semantics.

[bokelley]

Triage

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

What the experts said:

• ad-tech-protocol-expert: Option A alone fails for open-corpus keys per DR-0004; recommend constraint-tier (enum | pattern | string per declared key) reusing the existing governance.property_features discriminant pattern; need separate UNDECLARED_KEY vs UNDECLARED_VALUE error codes — they require different buyer-agent responses
• ad-tech-protocol-expert-deep: Staged A→B — ship A normative in 3.2, typed-open as x-status: experimental → normative in 3.3 after collecting real seller taxonomy data; pattern constraints validated at AdCP layer may not match ad-server acceptance, creating invisible failure modes worse than silent drop
• adtech-product-expert: Value enumeration is feasible for editorial keys (≤50 values) but structurally broken for DMP-keyed segment IDs; hard-reject semantics are correct for agentic buyers but need dedicated error codes and a capabilities.changed obligation when a key or value is retired
• adtech-product-expert-deep: Staged A→B; GAM open-string parity can wait without regression; under-declaration defeats the RFC if sellers with open-string keys must choose between exhaustive enumeration and omitting the key entirely; buyer_sent: true discriminator needed in capability declaration to prevent managed-injection keys being sent by buyers

My take: Experts converge that Option A alone is insufficient and that a typed-open mechanism is the right end state; they split on whether to land it normatively in 3.2 now or defer typed-open to 3.3 and ship finite-enum as the 3.2 normative base. Both paths require the same four cross-cutting resolutions before any schema lands.

---

Option A — Finite enumeration (keys + exhaustive value list; closed-enum only; simpler to validate):

// capabilities → media_buy.targeting_support.custom_targeting
{
  "keys": [
    { "key": "acme.content_genre", "values": ["news", "sports", "entertainment"] },
    { "key": "acme.content_rating", "values": ["G", "PG", "PG-13", "R"] }
  ]
}

Sellers with segment-ID or open-string keys cannot enumerate; predictable outcome is under-declaration (key omitted entirely), leaving those keys in local extensions — the gap the RFC exists to close.

Option B — Typed-open values (keys + optional constraint variant; handles segment-ID / DMP-backed / open-string keys):

// capabilities → media_buy.targeting_support.custom_targeting
{
  "keys": [
    { "key": "acme.content_genre",  "constraint_type": "enum",    "values": ["news", "sports"] },
    { "key": "acme.segment_id",     "constraint_type": "string" },
    { "key": "acme.age_score",      "constraint_type": "pattern", "pattern": "^\\d{1,3}$" }
  ]
}

// targeting_overlay — same wire shape for both options
{ "custom_targeting": { "acme.content_genre": ["news"], "acme.segment_id": ["seg_42"] } }

Pattern constraints validated at the AdCP layer may not match ad-server enforcement; WG needs real seller taxonomy data before pattern semantics can be specified normatively without creating invisible failure modes.

---

Cross-cutting requirements (apply regardless of path chosen):

1. Error code split: UNDECLARED_KEY (re-fetch capabilities) vs UNDECLARED_VALUE (inspect constraint and retry) are different buyer-agent actions; a single INVALID_REQUEST is unactionable
2. Invalidation obligation: retiring a key or value MUST trigger capabilities.changed; sellers MUST honour a grace period (≥ one cache_ttl_seconds) before hard-rejecting retired values on live campaigns
3. Buyer-sent discriminator: the capability declaration must distinguish keys buyers send from keys the seller injects server-side; without this, the first seller who adds a managed key to the capability document breaks buyer agents that echo it
4. Namespacing SHOULD convention: reverse-domain prefix on declared key names ("streamhaus.com:content_genre") prevents collision when an aggregated SSP publishes keys from multiple publisher partners in one capability document; key in the overlay must exactly match declared key including prefix

@bokelley — your call: B normative in 3.2 now, or staged A in 3.2 + B normative in 3.3? Both paths produce the same overlay wire shape; the only question is whether to lock in typed-open constraint semantics before we have seller taxonomy data to validate the pattern variant against real deployments.

---

Triaged by Claude Code.

---

Generated by Claude Code

[bokelley]

Closing as not planned after the targeting-model review in #6203.

Even capability-gated arbitrary keys would expose a seller's internal ad-server control plane without providing interoperable semantics, enforceable authorization boundaries, or mechanically verifiable privacy behavior. External buyers should use typed AdCP targeting fields, seller-published signals, structured inventory selection, and opaque configured products. Sellers remain free to compile those inputs into managed key/value controls internally, but buyer-supplied keys and values are not part of the protocol contract.

When a recurring concept needs cross-seller support, the path is a first-class typed field with explicit matching and resolution semantics. Browser-family RFC #6223 is an example of that approach.