RFC: sort/limit negotiation for automatic breakdowns (creative, keyword, catalog_item)

[bokelley]

Problem

reporting_dimensions gives buyers limit + sort_by (+ sort_direction per #6622) on the negotiated breakdown dimensions (geo, device_type, device_platform, audience, demographic, placement, format per #6616). But three breakdowns — by_creative, by_keyword, by_catalog_item — are returned automatically when the seller supports them and are not controlled by this object (request schema's own words). They have no limit, no sort_by, and no by_X_truncated disclosure.

Consequence: "top creatives by completion" — arguably the single most common buyer reporting question — is only answerable if the seller happens to return all creative rows. A seller with 500 creatives that returns 50 rows has no way to say which 50 or whether the list is complete, and the buyer has no way to ask for the top 50 by quartile_100 (sortable as of #6618).

Proposed direction

Add optional creative, keyword, catalog_item keys to reporting_dimensions with the standard {limit, sort_by, sort_direction} shape, plus by_creative_truncated / by_keyword_truncated / by_catalog_item_truncated and the applied-sort echo per the #6622 pattern.

The design wrinkle that makes this an RFC rather than a rider: these breakdowns are automatic today, so the semantics of omitting the new request key must stay "seller returns what it returns" (backward compatible), while presence upgrades the contract to negotiated limit/sort/truncation-disclosure. That presence/absence dual contract is new — every existing dimension is opt-in from scratch.

Relationship

• feat(reporting): add leaf metric identities for nested delivery values #6618 (leaf metric identities) makes completion/viewability sorting expressible; this RFC makes it reachable for creative rows.
• get_media_buy_delivery: *_truncated breakdowns are retrieval dead-ends #5671 (breakdown continuation) is the complement: sort+limit gets the top-N cheaply, continuation gets the rest. They should share truncation semantics.

🤖 Generated with Claude Code

[bokelley]

Triage

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

What the experts said:

• ad-tech-protocol-expert: Dual contract is logically coherent but missing an interop detection contract — a 3.2 buyer cannot distinguish a 3.1 seller (ignoring the new key, returning auto data) from a 3.2 seller (honoring negotiation). Applied-sort echo must be the MUST-strength discriminator; its absence must mean "treat as legacy uncontrolled return." Also raises a wire-shape issue: adding creative/keyword/catalog_item inside reporting_dimensions directly contradicts its own description ("not controlled by this object") and will cause implementer misread (key present = activate vs. parameterize?). Recommends a sibling object instead.
• adtech-product-expert: Problem confirmed real and high-priority across all three channels (CTV: creative by completion, search: keyword by ROAS, retail: catalog_item by units_sold). Major platforms all support server-side sort on these dimensions — realistic implementation ask. Dual contract is safe if and only if echo is MUST; anything weaker makes the negotiated path untrustworthy for agents. Two-phase approach (sort+limit now, continuation in get_media_buy_delivery: *_truncated breakdowns are retrieval dead-ends #5671) is correct — top-N is the complete answer for most buyers.

My take: Both experts converge on the same two conditions before this can ship. The RFC's core design is sound and the 3.2 milestone with the current cluster is correct — but these two questions are WG calls, not implementation calls.

---

Decision memo (pending WG ratification):

title: Sort/limit negotiation for automatic delivery breakdowns
class: normative
date: 2026-08-17
refs: ["#6623", "#6622", "#6618", "#5671"]
dissent: none — two design questions unresolved (see Q1, Q2 below)

Proposed ruling: Add optional limit / sort_by / sort_direction negotiation for by_creative, by_keyword, and by_catalog_item, with by_X_truncated disclosure and applied-sort echo. Key absent = legacy auto-return (backward compatible); key present = negotiated parameters.

Rationale: After #6618 + #6622 merge, buyers can express "top placements by completion rate" but not "top creatives by completion rate." The asymmetry is immediately visible; creative-by-completion is the dominant buyer query in CTV, and keyword/catalog_item cardinalities (thousands to millions of rows) make unbounded auto-return the most severe gap of the three. All major platforms support server-side sort on these dimensions — implementation path is straightforward.

Q1 — Wire shape (WG must decide):

Option A — In-band inside reporting_dimensions (as proposed). Requires updating the existing description that explicitly excludes these breakdowns.

{
  "reporting_dimensions": {
    "creative": { "limit": 50, "sort_by": "quartile_100", "sort_direction": "desc" },
    "geo": { "geo_level": "metro", "limit": 25, "sort_by": "spend" }
  }
}

Risk: sellers may misread creative: {} as "activate creative breakdown" rather than "tune the automatic one," mirroring the same misread the existing description was written to prevent.

Option B — Sibling object alongside reporting_dimensions. No description contradiction; semantically clean separation of activation (opt-in dimensions) vs. parameterization (automatic dimensions).

{
  "reporting_dimensions": { "geo": { "geo_level": "metro", "limit": 25 } },
  "automatic_breakdown_controls": {
    "creative": { "limit": 50, "sort_by": "quartile_100", "sort_direction": "desc" }
  }
}

Natural extension point for any future automatic breakdowns. Protocol expert recommends this option.

Q2 — Echo strength (experts agree; WG to confirm): Applied-sort echo (by_creative_sorted_by / by_creative_sort_direction, siblings to by_creative_truncated) must be MUST when the breakdown is present — not SHOULD. It is the only interop detection mechanism: an agent receiving by_creative rows with no echo cannot tell whether its sort request was honored.

Non-blocking (incorporate into implementation): New by_X_truncated flags should note additive compatibility with #5671's future cursor-sibling shape so that #5671 can add pagination without a schema break.

Hard dependencies: #6618 (leaf metric identities, open PR) → #6622 (sort direction + echo, open PR, stacked on #6618). Both must merge before this RFC can be implemented.

Implications: Non-breaking; MINOR bump on 3.2 line. Milestone omitted — ships as PR-shaped work once WG ratifies.

---

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

---

Generated by Claude Code

[bokelley]

Implementation is open (see the newly linked PR above, top of the #6618 stack). The presence/absence dual contract landed as proposed, with the review-driven refinement that the truncation/echo MUSTs bind to request-key presence rather than array presence — array-presence MUSTs would have retroactively broken existing automatic emissions. The applied-sort echo doubles as the capability-detection signal for sellers that predate negotiation.