RFC: frequency_capping capability declaration — what does a seller need to commit to?

[bokelley]

Open question

targeting.frequency_cap (core/targeting.json#L174) lets a buyer request a frequency cap on a package. There's no corresponding capability declaration on the seller side — buyers can't discover whether a seller will actually honor the cap, what dimensions it caps on, or what time windows it supports.

Compare to collection_list on the same schema, which explicitly notes "Seller must declare support in get_adcp_capabilities." Frequency capping doesn't have that hook.

Two questions for the WG:

1. What does "I support frequency capping" mean?

Possible shapes:

(A) Presence-only object — same pattern as conversion_tracking. Mere presence of frequency_capping: {} means the seller honors targeting.frequency_cap. Minimal, but doesn't communicate dimensions/granularity.

(B) Capability object with declared dimensions:

\"frequency_capping\": {
  \"supported_scopes\": [\"impression\", \"reach\"],    // cap on raw impressions vs unique users
  \"supported_windows\": [\"hour\", \"day\", \"week\", \"month\", \"campaign\"],
  \"min_cap\": 1,
  \"max_cap_per_period\": null,
  \"enforces_within\": \"package\" | \"buy\" | \"account\"
}

(C) Boolean — just frequency_capping: true. Cheapest, least informative.

Shape (B) is honest about what's variable in the field. Many sellers cap per-impression-per-day but not per-reach-per-week; some only enforce at the package level; some can only enforce within a single ad server's view.

2. How does this compose with target_frequency on reach goals?

optimization-goal.json declares target_frequency for reach optimization — a soft "prefer fresh reach" signal that's distinct from a hard cap. Does a seller advertising frequency_capping automatically support target_frequency, or are these independent capabilities?

My read: independent. frequency_cap is a hard targeting constraint; target_frequency is an optimization signal. A seller can support one without the other.

3. Does this need product-level or seller-level declaration?

metric_optimization is declared per-product; conversion_tracking is declared per-seller. Frequency capping could be either — different products on the same agent may have different caps. Most likely per-seller for the dimension declaration, per-product for limits (min/max).

Why now

media_buy_seller/frequency_cap_enforcement is on the storyboard backlog under #4637 — it would assert that a buy with targeting.frequency_cap set produces delivery whose observed frequency stays at-or-below the cap. The scenario needs a capability gate; without a declaration shape, the gate has nowhere to point.

Asks of the WG

1. Which shape — (A), (B), or (C)?
2. Should target_frequency support inherit from the same capability or stay independent?
3. Seller-level vs product-level (or both)?

Out of scope

• The storyboard scenario itself. That lands once the capability shape is settled.
• Reach measurement methodology. Frequency capping is a control, not a measurement.

Refs

• Meta: capability-claim contract scenarios — close the gap between what agents declare and what they do #4637 — capability-claim contract scenarios (meta tracking)
• core/targeting.json#L174 — existing frequency_cap field
• core/optimization-goal.json — target_frequency on reach goals (related but distinct)

[bokelley]

Triage

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

What the experts said:

• ad-tech-protocol-expert: Shape (C) is off the table — booleans have no precedent as top-level capability discriminators and are inextensible. Shape (B)'s enforces_within is unenforceable self-attestation (no SSP exposes enforcement topology via API; OpenRTB, GAM, and VAST all handle this out-of-band). supported_scopes: ["impression","reach"] introduces vocabulary not anchored to reach-unit.json. Shape (A) follows the conversion_tracking precedent exactly and is coherent.
• ad-tech-protocol-expert-deep: Neither (A) alone nor full (B) hits the right spot. The one dimension buyers actually need for pre-flight validation is which entity types (per values) the seller can count — without that, a buyer sending {per:"unique_user"} to a seller whose identity graph can only count devices gets a silent enforcement failure. Recommend a middle path: presence object + supported_per_units ($ref reach-unit.json) + supported_window_units (subset of duration.unit). Drop enforces_within entirely. target_frequency stays independent under metric_optimization at product level.
• adtech-product-expert: enforces_within won't reflect real SSP reality — enforcement scope varies by ad server and isn't something sellers can reliably commit to in a capability object. Seller-level coarse gate + per-product overrides (paralleling metric_optimization) is the right structure. Buyers primarily need to know: "does this seller honor per: unique_user caps or only per: devices?"

My take: (C) is out. (A) is safe to ship and non-breaking. Full (B) has two structural problems: supported_scopes/supported_windows don't align with the existing reach-unit.json / duration.json vocabulary, and enforces_within is attestation that no real SSP can back with an enforcement guarantee. The expert-recommended middle path is (A) with two aligned optional sub-fields.

@bokelley, your call between:

Option A — presence-only, sub-fields later:

// get-adcp-capabilities-response.json → media_buy
+ "frequency_capping": {
+   "type": "object",
+   "description": "Presence indicates seller honors targeting.frequency_cap and SHOULD reject
+                   caps it cannot enforce rather than silently dropping them."
+ }

Ships fast. Buyer agents get a binary gate; no pre-flight dimension validation.

Option B-lite — presence + aligned sub-fields (expert recommendation):

+ "frequency_capping": {
+   "supported_per_units": {
+     "type": "array",
+     "items": { "$ref": "/schemas/enums/reach-unit.json" },
+     "description": "Entity granularities the seller can enforce caps against.
+                     Omit to indicate all reach-unit values are supported."
+   },
+   "supported_window_units": {
+     "type": "array",
+     "items": { "type": "string" },
+     "description": "Duration units the seller supports for max_impressions windows
+                     (values from duration.json unit enum — 'hours', 'days', 'campaign', etc.)."
+   }
+ }

Example valid declaration: {"supported_per_units":["devices","individuals"],"supported_window_units":["days","campaign"]}. Gives buyers the two axes they need for pre-flight validation. enforces_within is dropped — no clean compliance story for it.

On Q2 (target_frequency): experts agree — independent capability, stays under metric_optimization at product level. No action needed in this RFC.

On Q3 (declaration level): seller-level coarse gate is correct for "I have cap infrastructure." Per-product overrides (for sellers with mixed addressable/non-addressable inventory) are a likely follow-up once the base shape is settled — worth noting whether that's in-scope for this RFC or deferred.

---

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

---

Generated by Claude Code