RFC: property dimension in get_media_buy_delivery reporting breakdowns (by_property)

[nastassiafulconis]

Problem

Buyers optimizing multi-publisher buys need to know where impressions actually delivered, at the level of the property (domain, app, CTV channel), so they can shift budget toward properties that perform. Today get_media_buy_delivery cannot answer "how many impressions ran on cnn.com vs bbc.com" for any buy.

This also breaks the protocol's own governance loop. validate_property_delivery consumes delivery records keyed by property identifiers:

{ "identifier": { "type": "domain", "value": "www.nytimes.com" }, "impressions": 103 }

and the documented feedback loop says step 1 is "pull delivery data via get_media_buy_delivery" - but no AdCP task produces delivery data in that shape. Buyers currently need log-level data or a verification vendor to feed AdCP's own governance validation.

What exists today

• reporting_dimensions on get_media_buy_delivery already supports request-controlled, capability-gated breakdowns: geo, device_type, device_platform, audience, placement, each with limit, sort_by, and a *_truncated flag.
• by_placement rows MAY carry publisher_domain (the adagents.json namespace). That gives namespace attribution, but placement granularity is finer than property, and top-N truncation (default 25) means per-domain totals cannot be reconstructed from placement rows on large buys.
• Discovery recently gained a publisher_domain filter on get_products (feat(training-agent): add publisher_domain filter to get_products #5867). Buyers can now select inventory by publisher namespace but cannot attribute delivery back to it - the loop doesn't close.
• publisher_properties (required on every product) declares the coverage claim at discovery time. This RFC adds the delivery truth to pair with it.

Proposal

Additive, minor-safe. Follows the existing dimension pattern exactly.

Request - new key in reporting_dimensions:

{
  "reporting_dimensions": {
    "property": { "limit": 50, "sort_by": "spend" }
  }
}

Response - by_property (+ by_property_truncated) within each by_package entry. Each row is delivery-metrics plus identity:

{
  "by_property": [
    {
      "identifier": { "type": "domain", "value": "cnn.com" },
      "publisher_domain": "cnn.com",
      "property_id": "prop_cnn_web",
      "impressions": 450000,
      "spend": 2250.00
    },
    {
      "identifier": { "type": "android_package", "value": "com.cnn.mobile.android.phone" },
      "publisher_domain": "cnn.com",
      "impressions": 120000,
      "spend": 600.00
    }
  ],
  "by_property_truncated": false
}

• identifier (required): {type, value} using the existing property identifier vocabulary. This is what the seller's ad server operationally knows (serving domain, app bundle), and it makes by_property rows directly consumable by validate_property_delivery - reporting output becomes governance input with metrics attached.
• publisher_domain, property_id (optional): enrichment when the seller can resolve the identifier to a registered property, same SHOULD/MAY posture as by_placement.publisher_domain.

Capability: supports_property_breakdown boolean in reporting_capabilities, consistent with the other dimension flags.

Scope notes

• Actuals only. This does not require products to enumerate property composition beyond what publisher_properties already declares. The ad server knows where impressions served even for run-of-network products. Once actuals exist, buyers also learn effective composition empirically.
• Cardinality: run-of-network buys can span tens of thousands of properties. The existing limit/sort_by/truncated pattern handles this the same way it does for placement and postal-level geo.
• Seller sensitivity: domain-level delivery can reveal supply mix. Capability-gating keeps it opt-in, same as every other dimension. Direct/guaranteed sellers already share site-level reporting in traditional IOs.
• Per-dimension only: no cross-dimensional intersections, per the existing rule.

Open questions

1. Is identifier the right required identity, with property_id/publisher_domain optional? (Alternative: require registry resolution, which adds seller burden and fails for unregistered properties.)
2. Naming: property (channel-neutral, matches the property model) vs domain (web-biased). This RFC proposes property.
3. Do windowed webhook payloads need parity, or is pull-only sufficient for optimization cadence (like other request-controlled dimensions)?
4. Should there be a minimum-row threshold or other aggregation floor for sellers with privacy constraints?

[bokelley]

Triage

Classification: Feature request (RFC — non-breaking minor addition)
Bucket(s): spec / protocol, media-buy
Status: ready-for-human
Milestone: Spec Backlog

What the experts said:

• ad-tech-protocol-expert: MINOR bump, non-breaking throughout (additionalProperties: true on all three affected schemas); exact pattern match to the existing dimension framework; industry precedent is strong (OpenRTB Site/App objects, ads.txt/sellers.json, every major ad server exposes domain/bundle-level reporting). One spec-text caveat: delivery-record.json is additionalProperties: false with only {identifier, impressions} — by_property rows extend delivery-metrics.json and therefore cannot be passed directly to validate_property_delivery; callers must project {identifier, impressions} out first. The RFC text calling rows "directly consumable" needs a precision fix.
• adtech-product-expert: Use case is real and unsatisfied by by_placement (placement granularity is finer than property; top-N truncation makes domain-total reconstruction impossible on large buys). Ad-network sellers have the operational data; confidentiality obligations around supply mix justify opt-in via capability flag rather than mandatory disclosure. CTV sellers may genuinely lack per-app granularity — not obstruction, just ad-server reality; spec should acknowledge graceful degradation there.
• ad-tech-protocol-expert-deep: Q1–Q3 resolve on technical grounds; Q4 is the only policy call. Expert recommendation on Q4: sellers should declare an optional property_breakdown_min_impressions in the capability object rather than silently suppressing rows — silence means no floor, declared value tells buyers exactly what data completeness to expect before requesting the breakdown.

My take: All three experts converge — RFC is well-scoped, non-breaking, closes the protocol's own governance loop, and has strong industry precedent. Three of four open questions resolve without a WG vote; only Q4 (privacy aggregation floor) is a genuine policy call. Decision memo below for WG ratification.

---

Decision Memo (pending WG ratification — commit to governance/decisions/ verbatim on approval)

id: DR-PENDING
title: Add `property` dimension to get_media_buy_delivery reporting_dimensions
class: normative
status: recorded
date: 2026-07-16
decided: ~2026-07 (pending WG ballot)
decided_by: WG ballot
refs: ["#5880"]
dissent: none recorded

Decision

Add a property reporting dimension to get_media_buy_delivery, following the established {limit, sort_by} / by_* / by_*_truncated / supports_*_breakdown pattern:

Request — new optional key in reporting_dimensions:

{ "reporting_dimensions": { "property": { "limit": 50, "sort_by": "spend" } } }

Response — by_property + by_property_truncated within each by_package entry:

{
  "by_property": [
    {
      "identifier": { "type": "domain", "value": "example.com" },
      "publisher_domain": "example.com",
      "impressions": 450000, "spend": 2250.00
    },
    {
      "identifier": { "type": "android_package", "value": "com.example.app" },
      "impressions": 120000, "spend": 600.00
    }
  ],
  "by_property_truncated": false
}

Row schema: allOf[delivery-metrics.json, {identifier (required, $ref core/identifier.json), publisher_domain (optional), property_id (optional)}] with required: [identifier, impressions, spend]. publisher_domain and property_id are optional enrichment (same SHOULD/MAY posture as by_placement.publisher_domain).

Capability: New optional boolean supports_property_breakdown in reporting_capabilities.json, consistent with the existing six breakdown flags.

Q1 — Identity anchor (settled): identifier is required; publisher_domain and property_id are optional enrichment. Registry resolution is NOT required. The ad server's operationally known serving domain or app bundle is the authoritative identity — mandating property_id would block any seller whose inventory is not yet in the AdCP registry.

Q2 — Naming (settled): Dimension key is property, response array is by_property. domain is rejected as web-biased and incompatible with the spec's 20-type identifier-types.json taxonomy (app bundles, CTV channels, DOOH venues, broadcast station IDs). property is already load-bearing in the protocol (publisher_properties, validate_property_delivery) and consistency is worth more than brevity.

Q3 — Webhook parity (settled): Pull-only for this revision. Property breakdowns are a verification/optimization signal suited to periodic pull; including them in windowed webhook payloads would bloat payload sizes for run-of-network campaigns spanning thousands of properties. Reserve supports_property_breakdown_webhook as a named extension point for a future minor if demand materializes.

Q4 — Privacy aggregation floor (WG vote needed):

Option A — no normative floor; sellers suppress rows silently at their discretion:

{ "supports_property_breakdown": true }

Simple; opaque to buyers on data completeness.

Option B — capability-declared floor (expert recommendation):

{ "supports_property_breakdown": true, "property_breakdown_min_impressions": 50 }

Sellers MUST populate property_breakdown_min_impressions when a floor is in effect; absence means no suppression. Supports cross-jurisdiction k-anonymity compliance (GDPR DPAs and US state laws set differing thresholds) and gives buyers full data-completeness visibility before requesting the dimension.

Rationale

Property-level delivery attribution is unsatisfied by by_placement (placement granularity is finer; truncation prevents reconstruction on multi-publisher buys). The identifier shape aligns with validate_property_delivery's input contract (property/delivery-record.json), completing the protocol's agentic governance loop. The change is additive, backward-compatible with all 3.0.x consumers, and targets main → 3.1.0-beta.N (not patch-eligible per stable-schema rules).

Implications

• Q1–Q3 are settled by this memo and do not require further WG discussion.
• Q4 requires WG ballot before spec text is written.
• Spec text must include a note that callers wishing to pass by_property rows to validate_property_delivery must project {identifier, impressions} — the row schema extends delivery-metrics.json while delivery-record.json is additionalProperties: false.
• CTV sellers aggregating at network/channel-group level and lacking per-app delivery data MAY declare supports_property_breakdown: false; this is not a conformance failure.
• Webhook parity for this dimension is explicitly out of scope for this revision.

---

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

---

Generated by Claude Code