Reporting metric aggregation needs executable semantics

[bokelley]

Problem

AdCP 3.2.0-rc.0 report-definition metrics declare aggregation as
sum | count | min | max | average | ratio | last | custom. Merged Reliable Reporting
PR #7228 adds immutable revision/receipt machinery but does not make metric aggregation
semantics executable.

Even for one bilateral seller feed, a generic buyer cannot safely determine:

• a ratio's numerator, denominator, and zero-denominator behavior;
• semantic compatibility across qualifier/population/time/attribution windows;
• additive versus semi-additive axes;
• non-additive unique versus modelled/deduplicated values;
• when last is ordered by observation, data-through, or source sequence.

Separately, get_media_buy_delivery.aggregated_totals.reach permits either true
cross-buy deduplicated reach or a sum of per-buy reach under the same field. Those have
different population semantics, and summed constituent reach must not feed frequency as
if it were unique reach.

This is a bilateral interpretation gap, not a request to standardize a buyer's
cross-seller portfolio aggregation engine.

Proposed additive shape

Keep legacy string values for compatibility and add a discriminated semantic object to
report-definition metrics, for example:

{
  "name": "ctr",
  "source_expression": "clicks / impressions",
  "aggregation": {
    "kind": "recomputable_ratio",
    "numerator_metric": "clicks",
    "denominator_metric": "impressions",
    "zero_denominator": "null"
  },
  "unit": "ratio",
  "population": "served_ad_events:v1",
  "window_basis": "report_period",
  "compatibility_key": "sha256:..."
}

The union should distinguish at least additive, recomputable ratio, semi-additive,
non-additive unique, deduplicated/modelled, last-value/snapshot, and
opaque/custom-unsafe. For aggregate reach, add method/model/population evidence; absent
that evidence, omit aggregate reach or label a sum explicitly as a bound such as
sum_of_constituent_reach, which cannot feed frequency.

Executable acceptance examples

1. Compatible outbound-click counts sum; outbound clicks and all-clicks do not.
2. CTR is recomputed from compatible summed clicks/impressions and row CTR is never
   averaged.
3. Cross-buy reach without dedup population evidence is omitted or bounded; a pinned
   compatible dedup/model identity permits the unique value.
4. Source-local provisional and official values remain separate semantic partitions.
5. Different attribution windows cannot occupy one aggregate.
6. Existing legacy strings validate but are treated as unsafe for generic aggregation
   unless the missing semantics are supplied.

Out of scope: seller selection, multi-seller comparable-group selection, portfolio FX,
or any Interchange-specific report surface.

[bokelley]

Triage

Classification: Feature request — normative protocol addition
Bucket(s): spec / protocol, schema
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Both gaps are genuine wire-level interpretation failures — reach_window is orthogonal to dedup scope, and ratio/last leave conformant implementations free to compute materially different values. Discriminated union is structurally sound (same basis discriminator pattern already in finality_policies in this file) and non-breaking. Recommends splitting: reach dedup evidence → 3.2.0-rc.x (narrow additive field), full union → 3.3 (three open questions block it: compatibility_key canonicalization, last ordering-basis enum, custom escape-hatch URI).
• adtech-product-expert: Reach dedup is the clearest bilateral gap and most actionable piece. Full discriminated-union has adoption risk — sellers pin existing definition IDs and won't update optional fields without buyer-side pull. compatibility_key sha256 creates a canonical-serialization coordination problem no current DSP/SSP stack solves. Suggests: (a) narrow dedup_scope field for reach, (b) normative SHOULD on source_expression for ratio metrics as a bridge until the full union is ready.

My take: Experts agree the reach dedup gap is real and undercovered by current semantics, and that the full discriminated-union carries open design questions that need resolution before it can ship. The split is: narrow reach fix is low-risk and fits 3.2.0-rc.x; the full semantic union belongs in 3.3 pending answers on the three open design questions below.

Option A — Narrow 3.2.0-rc.x reach fix (both experts support):

// delivery-metrics.json — optional reach_dedup sibling to reach_window
{
  "reach": 450000,
  "reach_unit": "persons",
  "reach_window": { "kind": "cumulative" },
  "reach_dedup": {
    "is_deduplicated": true,
    "scope": "cross_buy"
  }
}
// Absent reach_dedup or is_deduplicated: false → MUST NOT feed frequency denominator

Additive optional field on delivery-metrics.json (additionalProperties: true today). Closes the frequency-from-constituent-sum footgun at zero migration cost.

Option B — Full semantic union (3.3, pending answers):

// reporting-report-definition.json metrics item
- "aggregation": { "type": "string", "enum": ["sum","count","min","max","average","ratio","last","custom"] }
+ "aggregation": {
+   "oneOf": [
+     { "type": "string", "enum": [...] },   // legacy — unsafe for generic aggregation per spec prose
+     { "type": "object", "properties": { "kind": {...}, "numerator_metric": {...}, ... }, "required": ["kind"] }
+   ]
+ }

Requires resolution of: (1) Is compatibility_key buyer-opaque grouping signal or a content-addressed URI (needs a canonical serialization spec either way)? (2) What are the enumerated ordering_basis values for last? (3) Does custom get a computable escape-hatch (URI/profile reference)?

@bokelley: Does Option A + a normative source_expression SHOULD for ratio metrics land as 3.2.0-rc.x work? For Option B timeline: is compatibility_key a buyer-opaque opaque token or a content-addressed URI — or should it be dropped in favor of buyer-computed comparison of the semantic object fields directly?

---

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

---

Generated by Claude Code

[bokelley]

Human triage decision: split by release

The reach ambiguity and the general report-definition aggregation model need different timelines.

• 3.2: the narrow aggregate-reach/frequency correctness bug is now tracked in fix(reporting): disambiguate aggregate reach and frequency denominator #7251.
• 3.3: this issue retains the full executable aggregation-semantics work.

For the 3.3 design, retain the required legacy string aggregation and add a sibling aggregation_semantics discriminated object. Changing aggregation itself to string | object would make newly emitted objects fail older validators that require a string.

The semantic object still needs WG decisions for ratio operands and zero behavior, semi-additive axes, unique/modelled values, last ordering basis, and custom/profile references. Prefer explicit comparable fields over a compatibility_key hash unless the protocol first defines canonical serialization. Also, source_expression is already required for every metric, so adding a SHOULD for ratio metrics would not close the interoperability gap.