diff --git a/.changeset/dooh-impression-basis.md b/.changeset/dooh-impression-basis.md new file mode 100644 index 00000000000..1f8b0a85764 --- /dev/null +++ b/.changeset/dooh-impression-basis.md @@ -0,0 +1,11 @@ +--- +"adcontextprotocol": minor +--- + +Add the experimental DOOH impression basis (`media_buy.dooh_impression_basis`, RFC #7253). A DOOH `impressions` figure is `plays × audience multiplier`, and the new `enums/impression-estimation-basis.json` says where the multiplier comes from: `currency_measured`, `seller_modeled`, `sensor_measured` or `hybrid`. + +- Delivery: `dooh_metrics` carries `impression_basis`, `audience_multiplier` and `basis_metric`, the `vendor_metric_values[]` row a sensor audience comes from. A row mixing tiers reports `impression_basis_breakdown[]` instead: at least two entries with distinct tiers, summing exactly to the row, and no row-level tier or multiplier. `venue_breakdown[]` rows may carry the tier and `plays`, one per screen that played the spot, and no multiplier: a venue's audience per play is its `impressions / plays`. +- Forecast: forecast points, canonical ones included, carry `impression_basis`, `audience_multiplier` and `impression_basis_breakdown[]`, outside `metrics`. A breakdown includes the fallback the seller expects. +- Discovery: `dooh_placement_attributes` carries the planned tier and multiplier. + +`impressions` is authoritative and the multiplier is `impressions / plays`, rounded. `hybrid` is a seller model calibrated by sensors on the seller's own screens, never a published currency nor a mix of tiers. All fields are optional. `ooh_metrics.estimation_basis` is unchanged. diff --git a/docs/creative/channels/dooh.mdx b/docs/creative/channels/dooh.mdx index cc7cb21893d..bf996db6b13 100644 --- a/docs/creative/channels/dooh.mdx +++ b/docs/creative/channels/dooh.mdx @@ -256,6 +256,63 @@ Proof-of-play reporting uses `plays` for the raw playout count and `impressions` } ``` +## Impression basis (experimental) + +A DOOH `impressions` figure is `plays × audience multiplier`, and the multiplier can come from a measurement currency, the seller's own model, or a sensor counting the audience at each play. Sellers that declare `media_buy.dooh_impression_basis` in `experimental_features` say which, with the tiers of `enums/impression-estimation-basis.json`. Everywhere below, `impressions` is authoritative and `audience_multiplier` is `impressions / plays`, rounded: a receiver never rejects a multiplier that differs only by rounding. + +- **Discovery.** `dooh_placement_attributes.impression_basis` is the tier the seller plans to use for a placement, and `audience_multiplier` the audience per play its forecasts apply. A product mixing sensor-equipped screens and screens without a sensor declares each placement's tier. Discovery declares no fallback tier: the fallback a sensor-equipped placement expects shows in its forecast, and the realised one in delivery. +- **Forecast.** A single-tier point carries `impression_basis` and its planning `audience_multiplier`. A point covering plays expected on different tiers carries an `impression_basis_breakdown` instead, each entry with its planning multiplier. That breakdown SHOULD include the fallback the seller expects: the plays sensor-equipped screens are expected to estimate on `seller_modeled` while their sensor is not reporting. The same fields appear on the forecasts of `get_products`, `list_products` and the proposal tasks. +- **Delivery.** `dooh_metrics.impression_basis` is the tier of every play in the row. A row whose plays were estimated on different tiers reports `impression_basis_breakdown` instead. That includes a sensor-equipped screen that falls back to the seller's model while its sensor is not reporting. `basis_metric` points to the `vendor_metric_values[]` row the sensor audience comes from, whose `measurable_plays` is the sensor's coverage. A `venue_breakdown[]` row carries its tier and its `plays`, one per screen that played the spot, but no multiplier: its audience per play is `impressions / plays`. + +`hybrid` is a seller model calibrated by sensors on the seller's own screens, whoever supplies them, never a published currency figure and never a mix of plays on different tiers, which the breakdown reports. + +### Rows mixing tiers + +When a delivery row's plays were estimated on different tiers, the seller MUST: + +1. Omit the row's `impression_basis`. Never substitute `hybrid` or the majority tier. +2. Report one `impression_basis_breakdown` entry per tier present: at least two entries, with distinct tiers, whose `plays` and `impressions` sum exactly to the row's. +3. Report the fallback plays of a sensor-equipped screen, estimated while its sensor was not reporting, as `seller_modeled`. +4. Make each tier entry of a parent row (the totals, a package) equal the sum of its child rows' entries for that tier, a child with a single tier counting as one entry. +5. Omit the tier on a `venue_breakdown[]` row that mixes tiers. + +A row never carries both `impression_basis` and a breakdown, and SHOULD omit its own `audience_multiplier`, each entry carrying its own. A forecast point covering several tiers follows the same rules. + +### Reading the basis + +- **Tiers are different units.** A sensor counts the people in its zone, a currency usually publishes a visibility-adjusted "likely to see" figure, and a seller model is traffic-based. There is no exchange rate between them: compare impressions within a tier, and plays and spend across tiers. Within `sensor_measured`, compare only rows with the same `basis_metric`: a sensor counting people in front of a screen and a turnstile counting entries are different units too. +- **Billing is unchanged.** A CPM bills the row's total `impressions`, all tiers together. +- **A blended multiplier misleads.** A multiplier over plays on several tiers mixes those units, which is why a row with a breakdown omits it. +- **A filter on `impression_basis` misses mixed rows.** A row with a breakdown has no row-level tier: read the breakdown. +- **The tier is not OpenRTB's `qty.sourcetype`.** `sourcetype` says who supplies the multiplier, the tier says how it is derived. A third-party sensor vendor is `sourcetype` 1 and `sensor_measured`. + +A placement row whose sensor-equipped screens fell back to the seller's model for part of the flight: + +```json +{ + "placement_id": "concourse_screens", + "impressions": 510333, + "spend": 4082.66, + "plays": 27805, + "dooh_metrics": { + "screens_used": 85, + "impression_basis_breakdown": [ + { "impression_basis": "sensor_measured", "plays": 21340, "impressions": 397808, "audience_multiplier": 18.64 }, + { "impression_basis": "seller_modeled", "plays": 6465, "impressions": 112525, "audience_multiplier": 17.41 } + ], + "basis_metric": { "vendor": { "domain": "metro-media.example" }, "metric_id": "people_counted" } + }, + "vendor_metric_values": [{ + "vendor": { "domain": "metro-media.example" }, + "metric_id": "people_counted", + "value": 397808, + "unit": "persons", + "measurable_plays": 21340, + "vendor_relationship": "first_party" + }] +} +``` + ## Structured location for planning and mapping Coordinates and street address are location metadata, not placement identity: a missing, imprecise, or later-corrected `location` MUST NOT change `placement_id` or `identifiers[]`. Two disclosure shapes cover the concrete and aggregate cases from [#5538](https://github.com/adcontextprotocol/adcp/issues/5538): diff --git a/docs/media-buy/media-buys/optimization-reporting.mdx b/docs/media-buy/media-buys/optimization-reporting.mdx index 6b7c545baf2..4f0d1005754 100644 --- a/docs/media-buy/media-buys/optimization-reporting.mdx +++ b/docs/media-buy/media-buys/optimization-reporting.mdx @@ -231,13 +231,14 @@ A delivery or audience figure can carry several independent provenance fields. E | `completion_source` | Who **attested to the completion event** behind `completion_rate`? | `seller_attested` or `vendor_attested` | `qualifier.completion_source` on commitments, missing metrics, and delivery values | The `completion_rate` metric only | | `demographic_system` | What **notation** is the demographic code written in? | Notation enum (for example `nielsen`, `barb`, `nmo`, `videoamp`, `custom`) | `by_demographic` rows, demographic reporting capability, forecasts, and `cpp` pricing | One demographic code. Notation only: it does not say whose panel produced the number. | | `estimation_basis` | How was `estimated_impressions` **derived** (static OOH)? | `currency_measured` or `seller_modeled` | `ooh_metrics.estimated_impressions` (experimental) | One OOH delivery row | +| `impression_basis` | How was the audience multiplier behind DOOH `impressions` **derived**? | `currency_measured`, `seller_modeled`, `sensor_measured`, or `hybrid`; a row mixing tiers reports `impression_basis_breakdown` instead | `dooh_metrics` on delivery rows, forecast points, and `dooh_placement_attributes` (experimental, [DOOH impression basis](/docs/creative/channels/dooh#impression-basis-experimental)) | One DOOH delivery row, forecast point, or placement | | `circulation_basis` | How was `circulation_delivered` **derived** (print)? | `audited` or `seller_modeled` | `print_metrics.circulation_basis` on `by_installment` rows (experimental) | One print installment | | `match_rate_basis` | Did the platform **report** `effective_match_rate`, or did the seller compute it? | `platform_reported` or `derived` | Each audience in a [`sync_audiences`](/docs/media-buy/task-reference/sync_audiences) result, beside `audience_size` and `targetable_size` | One audience match result | How the fields combine: - **Provider versus vendor.** `measurement_source` names a provider as a slug on a measured-channel row. `vendor` names a vendor as a BrandRef on a vendor-defined metric, and `vendor_relationship` says how that vendor stands relative to the seller. Neither is a quality ranking, and neither implies the other. -- **Tier, not provider.** `estimation_basis` and `circulation_basis` record how a figure was derived. The provider rides `measurement_source`, so an `audited` circulation figure still names its auditor there. Currencies change over time, so tier values stay stable while provider slugs vary. +- **Tier, not provider.** `estimation_basis`, `impression_basis` and `circulation_basis` record how a figure was derived. The provider rides `measurement_source`, so an `audited` circulation figure still names its auditor there. Currencies change over time, so tier values stay stable while provider slugs vary. - **Notation, not provenance.** `demographic_system` only fixes how `P25-54` or `M25-54` is written. Report the provider that measured the audience in `measurement_source`. - **Attestation.** `completion_source` and `vendor_relationship` both distinguish seller-produced from independent figures. `completion_source` applies to `completion_rate` only. `vendor_relationship` applies to every vendor-defined metric. - **Basis of a rate.** `match_rate_basis` qualifies a rate, not a count: a `derived` rate computed from approximate or bucketed `audience_size` values is itself approximate. diff --git a/docs/media-buy/product-discovery/media-products.mdx b/docs/media-buy/product-discovery/media-products.mdx index 1627da4b62a..bdff1a845ce 100644 --- a/docs/media-buy/product-discovery/media-products.mdx +++ b/docs/media-buy/product-discovery/media-products.mdx @@ -455,6 +455,8 @@ Digital out-of-home placements can declare structured selling-unit metadata via | `loop_duration_seconds` | integer | Duration of the full ad loop rotation in seconds. Buyers derive nominal slot share as `slot_duration_seconds / loop_duration_seconds`. This is the canonical source; the pricing-layer field in `flat-rate-option` is superseded | | `screen_resolution` | object | Physical screen resolution (`{ width, height }` in pixels). Buyers derive aspect ratio from `width / height`. Omit for audio-only placements | | `motion` | string | Motion capability of a visual screen: `full_motion` (video), `partial_motion` (animated stills), or `static` (images only). Omit for audio-only placements | +| `impression_basis` | string | Experimental (`media_buy.dooh_impression_basis`), product and canonical placements only: the tier the seller plans to estimate the audience on (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`). See [DOOH impression basis](/docs/creative/channels/dooh#impression-basis-experimental) | +| `audience_multiplier` | number | Experimental (`media_buy.dooh_impression_basis`), product and canonical placements only: planning audience per play, the `impressions / plays` the seller's forecasts apply | All fields are optional. A single visual screen/frame placement can include all fields; an audio-only placement can declare only its slot and loop timing. A package or network placement should include only fields that are uniform across the included inventory. After publisher and product declarations are resolved, `slot_duration_seconds` MUST NOT exceed `loop_duration_seconds`. diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index 8bb391eb575..6448f2dda3b 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -154,6 +154,7 @@ Schemas marked with `x-status: experimental` are the authoritative source. The c | `media_buy.collection_lists` | The `collection_lists` and `collection_lists_exclude` fields on `targeting.json` and `targeting-input.json`, and the matching `overlay_support` / `required_overlay_support` keys with `max_references` ([#7834](https://github.com/adcontextprotocol/adcp/issues/7834)). See [Combining several collection lists](/docs/governance/collection/index#combining-several-collection-lists-experimental). | One buyer-side adopter so far, and the WG has not ratified the intersection/union semantics or the `max_references` shape. The singular `collection_list` fields are stable and unchanged. | | `signing.web_bot_auth` | The [Web Bot Auth request-signing profile](/docs/building/by-layer/L1/wba-profile): the `web-bot-auth` value in `request_signing.profiles` and `webhook_signing.profiles` on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities), and `signing_profile` on every webhook registration, adopted by DR-0023 | The profile follows an IETF draft that is still changing. The draft revision it pins and the `Signature-Agent` form may change before graduation. | | `media_buy.offline_delivery_metrics` | The `ooh_metrics` delivery block on `core/delivery-metrics.json` (panels, posting periods, posting records, share of voice, modeled `estimated_impressions` with `estimation_basis`; added in 3.2 and documented in [Out-of-home](/docs/creative/channels/ooh)), and the `print_metrics` delivery block (`page_delivered`, `position_delivered`, `circulation_delivered`, `circulation_basis`, `evidence`; added in 3.3 and documented in [Print creative](/docs/creative/channels/print#delivery-evidence-and-circulation)). Both carry `x-status: experimental`, both are addressable as `ooh_metrics` / `print_metrics` in the `available-metric` enum, and both reuse the channel-neutral `core/placement-evidence.json` artifact. | Delivery reporting for channels with no play or impression event — static OOH posting records and print proof-of-insertion with circulation — rests on one named adopter per channel and on contract conventions (OAAA proof of performance, tearsheets, circulation audits) that have not been field-tested across parties. `ooh_metrics` shipped in 3.2 without a registry row; this row registers it with `print_metrics` as a clarification, so a seller on 3.3 that reports either block declares the id. A seller on a 3.2 schema that already reports `ooh_metrics` is not made non-conformant retroactively. Field shapes, the `estimation_basis` / `circulation_basis` tier vocabularies, and the shared evidence artifact may change before they freeze. | +| `media_buy.dooh_impression_basis` | The `enums/impression-estimation-basis.json` tier enum (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`); on DOOH delivery rows of `core/delivery-metrics.json`, `dooh_metrics.impression_basis`, `audience_multiplier`, `basis_metric` and `impression_basis_breakdown[]` (`core/impression-basis-breakdown-entry.json`), and `impression_basis` / `plays` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/forecast-point.json` and `core/canonical-forecast-point.json`; and the planned `impression_basis` / `audience_multiplier` in the product and canonical `dooh_placement_attributes` ([RFC #7253](https://github.com/adcontextprotocol/adcp/issues/7253)). See [Impression basis](/docs/creative/channels/dooh#impression-basis-experimental). | Tells a buyer what kind of number a DOOH `impressions` figure is (`plays × audience multiplier`). One production adopter so far, whose network mixes sensor-measured and seller-modeled screens. Decided in the working-group brief on #7253: `hybrid` is a seller model calibrated by sensors on the seller's own screens, never a currency and never a mix of tiers; a row mixing tiers reports a breakdown of at least two distinct tiers, never beside a row-level tier; the multiplier is SHOULD on `sensor_measured` and `hybrid` rows, optional on `currency_measured` ones. `impression_basis` becomes required for the `sales-dooh` claim in 4.0. `ooh_metrics.estimation_basis` keeps its inline two-value enum. `list_products` and the proposal tasks carry the forecast fields through the canonical forecast point. | | `account.invoice_lines` | The optional `lines[]`, `invoice_kind` (`enums/invoice-kind.json`), and `adjusts_invoice_id` on `invoices[]` items of [`get_account_financials`](/docs/accounts/tasks/get_account_financials), and the `core/invoice-line.json` shape ([#8184](https://github.com/adcontextprotocol/adcp/issues/8184)) | Ties each invoice amount to the media buys, packages, official reporting revisions, and reporting adjustments it bills, so a buyer can reconcile what it was charged for against what was finalized. Reference only: it never creates, approves, or settles invoices. Single-adopter so far, and the ids it references come from `media_buy.reporting_delivery`. May change: itemised `lines[]` keyed to `reporting_revision_ids`, credit notes as `invoice_kind: credit_note` with a non-negative `amount` rather than a negative amount. The line shape is reusable so a later account-change-feed invoice notification can carry `lines` unchanged. | | `signals.pricing_groups` | The optional `pricing_group` field on the shared signal-listing fields (`get_signals` results and `Product.signal_targeting_options[]`), and `signal_pricing_group_rules[]` (schema: `core/signal-pricing-group-rule.json`) on `signal_targeting_rules` and the `get_signals` response (#7898) | Defines how fees of signals sharing a pricing group combine, a new commercial rule backed so far by one adopter (one adopter applies `highest` today as a platform default). Decided 2026-10-24 for 3.3 beta.1 ([#7898](https://github.com/adcontextprotocol/adcp/issues/7898)): a group with no rule is charged `each`, and `percent_of_media` is always `each` (no conversion rule). The `signal_charges[]` echo of per-signal charges on package state is a follow-up, so buyers reconcile against the published rules for now. | diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index 0d09b8160bf..71c9022ce21 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -924,6 +924,7 @@ Each is optional and experimental: a seller that emits it lists the feature id i - **Provider-initiated signal delivery (`signals.delivery_methods`, [#8044](https://github.com/adcontextprotocol/adcp/pull/8044), [#6552](https://github.com/adcontextprotocol/adcp/issues/6552)).** A signal agent declares `signals.delivery_methods[]` on `get_adcp_capabilities`, with the same pattern vocabulary as audience activation methods read from the send side. An `activate_signal` agent destination may pin a `delivery_method`; with no pattern and vendor intersection the destination fails with `UNSUPPORTED_FEATURE`, and a pin sent to an agent that doesn't list it is rejected the same way. Agent deployments gain `delivery_status` (`awaiting_read`, `delivered`, `failed`), a `delivery` descriptor, `delivery_error`, and an optional match outcome. A receiver field not yet established fails the destination with `ACCOUNT_SETUP_REQUIRED`. See [Declaring delivery methods](/docs/signals/tasks/activate_signal#declaring-delivery-methods). - **Measurement provenance (`media_buy.measurement_provenance`, [#7940](https://github.com/adcontextprotocol/adcp/pull/7940)).** A shared `enums/collection-mechanism.json` vocabulary (`set_top_box`, `acr`, `panel`, `server_logs`, `client_tracker`, `sdk`) is used by `vendor_metric_provenance[]` on delivery metrics, which carries `mechanisms[]` and an optional `deduplicated` for a `vendor_metric_values[]` row, joined on `(vendor, metric_id, qualifier)`. A collection mechanism is not `measurement_source`, which stays the provider slug, and broadcast as-run logs stay airing evidence in `by_spot[]`. Sellers serving an older pin omit the field. `measurement_terms.billing_measurement.counting_mechanisms[]` is withdrawn at rc.0 and planned for the canonical measurement terms in 4.0. - **Audience evidence targets (withdrawn) and invoice lines.** `target_audiences[]` (`media_buy.audience_evidence_targets`, [#8215](https://github.com/adcontextprotocol/adcp/pull/8215)) is withdrawn at rc.0 and has no 3.3 wire form; purchases gain it in 4.0. `lines[]`, `invoice_kind`, and `adjusts_invoice_id` on `get_account_financials` invoices (`account.invoice_lines`, [#8207](https://github.com/adcontextprotocol/adcp/pull/8207)) tie an amount to the buys, packages, and reporting revisions it bills, and never settle an invoice. +- **DOOH impression basis (`media_buy.dooh_impression_basis`, [#8736](https://github.com/adcontextprotocol/adcp/pull/8736)).** A seller that reports DOOH `impressions` can declare the tier and the multiplier on placements, forecast points and `dooh_metrics`. A row mixing tiers reports `impression_basis_breakdown` and omits the row-level tier and multiplier. Buyers compare impressions within a tier only. ## Experimental surface notices diff --git a/docs/reference/release-notes.mdx b/docs/reference/release-notes.mdx index c68edbb3839..f1c1980fb34 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -39,7 +39,7 @@ Each prerelease is immutable. The `3.3-beta` documentation selector stays at bet - **Scheduled and human-gated buying:** `expected_confirmation_at` on `submitted` envelopes (#8016) and on `refine_proposals` finalize and hold extension (#8104, #8203); experimental `hold_policy`, `extend_hold`, hold ranking, and per-installment hold readback (#8140, #8097, #8255, #8257); experimental delegated composition with `product_ids_exclusive` and `terms_only` finalize (#7954); vendor-metric `outcome_target` goals (#7966); experimental governance `budget.periods[]` and `governance.supports_budget_periods` (#7965); `change_cutoff` on installment deadlines (#8054). - **Proposals and media buys:** experimental open opportunities with later proposals, `proposal.created`, and `list_proposals`, which also reads seller offers and filters by `media_buy_ids` (#8103, #8223); seller revisions advance on every committed change from any origin, with `history[].origin` and the creative `seller_revision` (#8159, DR-0031); the stable `sales-fixed-rate` specialism for fixed-price, non-guaranteed sellers (DR-0028), with `expected_confirmation_at` on `get_media_buys` (#7963); experimental forward-only lineage with `predecessor_media_buy_id` and `lineage_reason` on `buy_products` and `accept_proposal` (#8038; withdrawn from `create_media_buy` at rc.0); `error.mutation_outcome` on failed mutations (#7935); the `operator_fee` price adjustment kind (#8356). - **Delivery reporting:** `impressions` optional on delivery rows, version-gated (#8108); experimental spot lifecycle, makegood linkage, and break position (#8017); experimental print proof of insertion and circulation (#7936); experimental delivery `projection` on `by_package[]` rows (#8043); experimental installment lifecycle and proof of publication on `by_installment[]` rows (#8116); flat totals omitted for multi-qualifier metrics (#8055); property-grain rollup capabilities (#7982); `reporting_webhook.operation_id` (#7895); `reporting_webhook.authentication` and `artifact_webhook.authentication` optional on 3.3 requests (#8177); receivers ignore `aggregated_totals` in delivery webhooks (#8053); `custody` on Reliable Reporting report definition sources (#8213). -- **Channels:** structured DOOH `location` and `dooh_inventory_summary.venue_counts[]` (#7416); experimental minute-level dayparts (#8025); `nmo` and `videoamp` demographic systems, `mxf` and broadcast mezzanine codecs, and experimental `loudness` (#8019); the expanded broadcast TV guide (#8006). +- **Channels:** structured DOOH `location` and `dooh_inventory_summary.venue_counts[]` (#7416); experimental minute-level dayparts (#8025); `nmo` and `videoamp` demographic systems, `mxf` and broadcast mezzanine codecs, and experimental `loudness` (#8019); the expanded broadcast TV guide (#8006); experimental DOOH impression basis, `media_buy.dooh_impression_basis` (#8736). - **Accounts and audiences:** discovery and negotiation tasks never provision an account (#7848); the deprecation of natural-key account references after provisioning (#8123) and the `account.stable_account_id` capability (#8123, #8124), which the account identity model below deprecates; audience sizes as ranges and `match_rate_basis` (#8024); the `uids[].value` wire form per type (#8059); `invoice` records on the experimental account change feed (#8095); the change feed's `idempotency_key` echo and required `changed_paths` (#8160). - **Account identity and requests (beta.1 to beta.3):** a brand is its domain, plus `brand_id` where its `brand.json` lists several; an account is the seller's `account_id`, and `countries`, `currency`, `timezone`, `sandbox`, and `operator_unit` are attributes (#8474, #8280, #8442). Sellers MUST return and accept `account_id`; `sync_accounts` settings updates change attributes in place. The identity-rekey machinery is deprecated: `account.identity_updates`, `operator_identity`, `ACCOUNT_MOVED`, `ACCOUNT_IDENTITY_CONFLICT`, and `account.stable_account_id`. Experimental `account.requests`: `request_account` and its pending action (#8293), the single account write where supported, with `list_accounts` request reads (#8551), change outcomes `updated`, `matched`, and `created` (#8580), the opt-in `allow_separate_account` and `ACCOUNT_CHANGE_REQUIRES_NEW_ACCOUNT` (#8582), and money terms on resolved requests (#8620). - **Reporting subscriptions (experimental, beta.1 to beta.3):** `reporting_subscriptions` on `sync_principal` and exceptions-only `subscription_coverage` on `get_reporting_status`, under `media_buy.reporting_subscriptions` ([#8543](https://github.com/adcontextprotocol/adcp/issues/8543) Part B, #8552). Beta.2 and beta.3 settle the SDK findings and make coverage computable from the wire: #8585, #8588, #8593, #8596, #8607 (revocation means no access), #8613, #8616 (canonical vectors), #8617, #8618, #8619, #8621 (`reporting_subscription_probe`), and #8622. @@ -155,6 +155,7 @@ Per the [experimental status contract](/docs/reference/experimental-status#gradu | `media_buy.daypart_granularity` | `start_time` / `end_time` on daypart entries and `time_granularity` (#8025) | New in 3.3; experimental | May be reshaped by network and station targeting ([#5679](https://github.com/adcontextprotocol/adcp/issues/5679)) and the targeting-dimension error codes ([#6978](https://github.com/adcontextprotocol/adcp/issues/6978)). | | `creative.broadcast_loudness` | `loudness` on `video_hosted` params (#8019) | New in 3.3; experimental | The `standard` enum may grow, and the object may be reconciled with the flat `loudness_*` fields on `audio_hosted`. | | `media_buy.offline_delivery_metrics` | `print_metrics` on delivery metrics (#7936), registered with the 3.2 `ooh_metrics` block (#8077) | New in 3.3; experimental. A seller on 3.3 that reports either block declares the id | `position_delivered` stays free-form until a position vocabulary is agreed. Field shapes and the basis vocabularies may change. | +| `media_buy.dooh_impression_basis` | `impression_basis`, `audience_multiplier` and `impression_basis_breakdown[]` on `dooh_metrics` and forecast points, and `basis_metric` on `dooh_metrics`; the planned tier and multiplier on `dooh_placement_attributes` (#8736) | New in 3.3; experimental | `impression_basis` becomes required for the `sales-dooh` claim in 4.0. | | `governance.campaign` | Adds `budget.periods[]` and `governance.supports_budget_periods` (#7965) | Still experimental; additive change | No graduation planned for 3.3. | | `identity.trust_json` | `trust/v1/trust.json` and `trust/v1/trust-acknowledgements.json` schemas (#8067); agents identified by origin, no keys in the record (#8121) | New in 3.3; experimental | Its reader is the Web Bot Auth profile, which derives the record from an agent's origin (#8162); grants are read at `sync_accounts` (#8169). Publishers declare nothing. The document name and `/.well-known` path may change. | | `signing.web_bot_auth` | The Web Bot Auth profile: `web-bot-auth` in `request_signing.profiles` and `webhook_signing.profiles`, and `signing_profile` on webhook registrations (#7894); Web Bot Auth identities, revocation, and coexistence with the RFC 9421 profile (#8162) | New in 3.3; experimental | The pinned draft revision and the `Signature-Agent` form may change. | diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index ba63e23ad69..52125164272 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -159,6 +159,7 @@ These shipped before beta.3 and are summarized here with the rest. Everything ma - **Print proof of insertion and circulation (experimental).** `print_metrics` on `by_installment` rows reports the page and position delivered, circulation and its basis (`audited` or `seller_modeled`), and a tearsheet `evidence` record. See [Delivery evidence and circulation](/docs/creative/channels/print#delivery-evidence-and-circulation). - **Property-grain rollups.** `media_buy.features.supports_property_breakdown` and `supports_installment_property_breakdown` commit a seller to return `by_property` and `by_installment_property` on every product that declares the per-product flag. Two capability-gated scenarios grade it. See [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities). - **Structured DOOH location.** Concrete screens can carry `dooh_placement_attributes.location` (`lat`, `lon`, structured `address`), and network products can carry `dooh_inventory_summary.venue_counts[]`. Both are disclosure metadata; `location` never changes placement identity. See [DOOH](/docs/creative/channels/dooh#structured-location-for-planning-and-mapping). +- **DOOH impression basis (experimental, `media_buy.dooh_impression_basis`, [#8736](https://github.com/adcontextprotocol/adcp/pull/8736)).** Placements, forecast points and delivery rows can say where a DOOH `impressions` figure comes from: `currency_measured`, `seller_modeled`, `sensor_measured` or `hybrid`, with the `audience_multiplier` applied to plays. A row mixing tiers reports `impression_basis_breakdown` instead of one tier. Tiers are different units, so compare impressions within a tier only. See [Impression basis](/docs/creative/channels/dooh#impression-basis-experimental). - **Rows without impressions.** Delivery rows may omit `impressions` when the seller did not measure them, for example on rows that report plays or downloads instead. Absence means not measured, never zero; receivers do not derive impression-based rates, and sellers never omit it toward callers pinned below 3.3. See [Rows without impressions](/docs/media-buy/media-buys/optimization-reporting#rows-without-impressions). - **Delivery projection (experimental).** Top-level `by_package[]` delivery rows can carry an advisory `projection` of lifetime impressions and spend with a `projected_end_state` and `basis`. It is a forecast, not a delivery record. Feature id `media_buy.delivery_projection`. See [Delivery projection](/docs/media-buy/task-reference/get_media_buy_delivery#delivery-projection). - **Installment lifecycle and proof of publication (experimental).** `by_installment[]` rows can carry `installment_status` and a `publication` record (`published_at`, `posts[]`, optional `evidence`), so a creator post, newsletter edition, or podcast episode reports whether and where it ran. Feature id `media_buy.installment_lifecycle`. See [Installment lifecycle](/docs/media-buy/media-buys/optimization-reporting#installment-lifecycle-and-proof-of-publication). @@ -307,6 +308,8 @@ New feature ids are `media_buy.spot_lifecycle`, `media_buy.daypart_granularity`, rc.0 adds `media_buy.installment_refinement` and `media_buy.installment_creative_assignment` ([New in rc.0](#new-in-rc-0)). +rc.1 adds `media_buy.dooh_impression_basis`. + Beta.5 adds `media_buy.match_keys` ([above](#new-in-beta-5)), which stays experimental at 3.3 GA and extends the experimental `Product.identity` declaration and TMP provider registration with match keys. ## Clarifications and conformance diff --git a/package.json b/package.json index 9d61af3b837..ff006e54328 100644 --- a/package.json +++ b/package.json @@ -33,7 +33,7 @@ "verify:schema-discovery": "node scripts/verify-schema-discovery.mjs", "typecheck": "tsc --project server/tsconfig.json --noEmit && npm run typecheck:fixed-trace-rollout-tests", "typecheck:fixed-trace-rollout-tests": "node scripts/typecheck-fixed-trace-rollout-tests.mjs", - "test:schemas": "node tests/schema-validation.test.cjs && node --test tests/reserved-word-enum-replacements.test.cjs tests/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/sync-plans-human-review.test.cjs tests/sync-plans-validation-annotations.test.cjs tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/assignment-replace.test.cjs tests/assignment-operations-capability.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/url-pattern-loosening.test.cjs tests/closed-schema-additions-withdrawn.test.cjs tests/identity-absence-coherence.test.cjs tests/match-keys.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/collection-mechanism.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-report-definition-vectors.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/installment-refinement.test.cjs tests/installment-creative-assignment.test.cjs tests/get-products-deprecated-withdrawals.test.cjs tests/deprecated-task-withdrawals.test.cjs tests/collection-catalog.test.cjs tests/collection-copies-vectors.test.cjs tests/social-distribution-identifiers.test.cjs tests/account-change-record.test.cjs tests/notification-config-payload-view.test.cjs tests/account-requests.test.cjs tests/reporting-subscriptions.test.cjs tests/reporting-subscription-probe.test.cjs tests/reporting-subscription-coverage-vectors.test.cjs tests/reporting-subscription-coverage-properties.test.cjs tests/product-roster-coverage-vectors.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting", + "test:schemas": "node tests/schema-validation.test.cjs && node --test tests/dooh-impression-basis.test.cjs tests/reserved-word-enum-replacements.test.cjs tests/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/sync-plans-human-review.test.cjs tests/sync-plans-validation-annotations.test.cjs tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/assignment-replace.test.cjs tests/assignment-operations-capability.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/url-pattern-loosening.test.cjs tests/closed-schema-additions-withdrawn.test.cjs tests/identity-absence-coherence.test.cjs tests/match-keys.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/collection-mechanism.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-report-definition-vectors.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/installment-refinement.test.cjs tests/installment-creative-assignment.test.cjs tests/get-products-deprecated-withdrawals.test.cjs tests/deprecated-task-withdrawals.test.cjs tests/collection-catalog.test.cjs tests/collection-copies-vectors.test.cjs tests/social-distribution-identifiers.test.cjs tests/account-change-record.test.cjs tests/notification-config-payload-view.test.cjs tests/account-requests.test.cjs tests/reporting-subscriptions.test.cjs tests/reporting-subscription-probe.test.cjs tests/reporting-subscription-coverage-vectors.test.cjs tests/reporting-subscription-coverage-properties.test.cjs tests/product-roster-coverage-vectors.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting", "test:performance-feedback": "node --test --test-force-exit --test-timeout=30000 tests/performance-feedback-contract.test.cjs", "test:dist-schema-version-ids": "node --test --test-force-exit --test-timeout=30000 tests/dist-schema-version-ids.test.cjs", "test:examples": "node tests/example-validation-simple.test.cjs && npm run test:tmp-context-merge", diff --git a/static/schemas/source/core/canonical-forecast-point.json b/static/schemas/source/core/canonical-forecast-point.json index c2db6bf529f..b1c3f4b5a3b 100644 --- a/static/schemas/source/core/canonical-forecast-point.json +++ b/static/schemas/source/core/canonical-forecast-point.json @@ -4,12 +4,38 @@ "title": "Canonical Forecast Point", "description": "Compact forecast row with numeric ranges and identity-only measurement-vendor references.", "type": "object", + "dependencies": { + "impression_basis_breakdown": { + "not": { "required": ["impression_basis"] } + } + }, "properties": { "label": { "type": "string", "maxLength": 128 }, "budget": { "type": "number", "minimum": 0 }, "product_id": { "type": "string", "x-entity": "product" }, "dimensions": { "$ref": "/schemas/core/forecast-point-dimensions.json" }, "availability_status": { "$ref": "/schemas/enums/availability-status.json" }, + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). On a DOOH point that forecasts `impressions` from `plays`, the methodology tier the forecast uses, when it is the same for every expected play. When the point covers plays expected on different tiers, including the fallback plays a sensor-equipped screen is expected to estimate on `seller_modeled` while its sensor is not reporting, sellers MUST omit it, never substituting `hybrid` or the majority tier, and report `impression_basis_breakdown`; a point never carries both. Lets forecast and delivery reconcile on the same declaration. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). The planning multiplier of a single-tier DOOH point: `metrics.impressions.mid / metrics.plays.mid`, rounded. The impressions are authoritative: a receiver MUST NOT reject a multiplier that differs from that ratio only by rounding. A point that reports `impression_basis_breakdown` SHOULD omit it and give each entry's planning multiplier instead: a multiplier blended across tiers mixes different units and misleads. A declaration, not a forecastable metric, so it sits outside `metrics`." + }, + "impression_basis_breakdown": { + "type": "array", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). For a DOOH point covering plays expected on different tiers, one entry per tier with the expected plays and impressions behind the point's midpoints: at least two entries, whose tiers MUST be distinct and whose `plays` and `impressions` MUST sum exactly to `metrics.plays.mid` and `metrics.impressions.mid`, which a point carrying a breakdown therefore carries. It SHOULD include the fallback the seller expects: the plays sensor-equipped screens are expected to estimate on `seller_modeled` while their sensor is not reporting. A point never carries both this and `impression_basis`. Tiers are different units with no exchange rate, so compare impressions within a tier (and for `sensor_measured`, within the same metric), and plays and spend across tiers.", + "items": { "$ref": "/schemas/core/impression-basis-breakdown-entry.json" }, + "minItems": 2 + }, "metrics": { "type": "object", "properties": { diff --git a/static/schemas/source/core/canonical-placement.json b/static/schemas/source/core/canonical-placement.json index 6b2bb3c9190..8ec19643ba3 100644 --- a/static/schemas/source/core/canonical-placement.json +++ b/static/schemas/source/core/canonical-placement.json @@ -70,7 +70,20 @@ "$ref": "/schemas/enums/dooh-motion-type.json", "description": "Physical motion capability of a visual DOOH screen, not an accepted-format declaration. Omit for audio-only placements." }, - "location": { "$ref": "#/definitions/CanonicalDoohLocation", "x-added-in": "3.3.0" } + "location": { "$ref": "#/definitions/CanonicalDoohLocation", "x-added-in": "3.3.0" }, + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Methodology tier the seller plans to estimate this placement's audience on, so a buyer can compare and filter products before buying. A product mixing screens on different tiers declares it per placement. Delivery reports the realised tiers, which can include the seller's model on a sensor-equipped screen while its sensor is not reporting. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Planning audience per play for this placement: the `impressions / plays` the seller's forecasts use. Optional on `currency_measured` placements." + } }, "x-adcp-validation": { "verifier_constraints": { diff --git a/static/schemas/source/core/delivery-metrics.json b/static/schemas/source/core/delivery-metrics.json index 24305017886..98cee619cd9 100644 --- a/static/schemas/source/core/delivery-metrics.json +++ b/static/schemas/source/core/delivery-metrics.json @@ -278,6 +278,51 @@ "type": "string", "description": "Per-row supplementary methodology notes for DOOH impression calculation (e.g., 'rotation-based; 6-second slot weighted by 70% audience overlap'). Free-form prose for context that doesn't fit the structured measurement-vendor surface. Canonical methodology declarations belong on the measurement vendor's `get_adcp_capabilities.measurement.metrics[]` block where they're discoverable once and inherited across delivery rows; this field is for row-specific context (a particular daypart's calculation, a venue-mix exception) rather than the seller's general methodology." }, + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Methodology tier of the row's `impressions` when every play in the row was estimated on that tier. SHOULD be present whenever a DOOH row reports `impressions`. When the row's plays were estimated on different tiers, sellers MUST omit it, never substituting `hybrid` or the majority tier, and report `impression_basis_breakdown`; a row never carries both. A buyer filtering on this field therefore misses mixed rows and has to read the breakdown. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). The row's `impressions / plays`, rounded, so a buyer can compare rows. `impressions` is authoritative: a receiver MUST NOT reject a multiplier that differs from `impressions / plays` only by rounding. On `sensor_measured` and `hybrid` rows sellers SHOULD include it, and it is the realised ratio for the period, which varies by row. On `currency_measured` rows it is optional. A row that reports `impression_basis_breakdown` SHOULD omit it and give each entry's multiplier instead: a multiplier blended across tiers mixes different units and misleads." + }, + "basis_metric": { + "type": "object", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). On rows whose impressions are, wholly or through an `impression_basis_breakdown` entry, `sensor_measured` or `hybrid`, the `vendor_metric_values[]` row the sensor audience derives from, joined on `(vendor, metric_id, qualifier)`. That row carries the coverage (`measurable_plays`) and the seller–vendor relationship, and the vendor catalog the methodology. When `basis_metric` is present, a matching row MUST be present in the `vendor_metric_values[]` of the delivery row that carries this `dooh_metrics`. Totals and package rows MAY omit it when the rows below them carry it.", + "properties": { + "vendor": { + "$ref": "/schemas/core/vendor-metric-value.json#/properties/vendor", + "description": "Vendor of the `vendor_metric_values[]` row. Matches the row's `vendor`." + }, + "metric_id": { + "$ref": "/schemas/core/vendor-metric-value.json#/properties/metric_id", + "description": "Metric of the `vendor_metric_values[]` row. Matches the row's `metric_id`." + }, + "qualifier": { + "$ref": "/schemas/core/vendor-metric-value.json#/properties/qualifier", + "description": "The row's `qualifier`, repeated verbatim when the row carries one. Omit when the row has none." + } + }, + "required": ["vendor", "metric_id"], + "additionalProperties": true + }, + "impression_basis_breakdown": { + "type": "array", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). For a row that aggregates plays estimated on different tiers — a product mixing sensor-equipped screens and screens without a sensor, or a sensor-equipped screen whose fallback plays, estimated while its sensor was not reporting, are `seller_modeled` — one entry per tier present: at least two entries, whose tiers MUST be distinct and whose `plays` and `impressions` MUST sum exactly to the row's. Each entry of a parent row (totals, a package) MUST equal the sum of its child rows' entries for that tier, a single-tier child counting as one entry. A row never carries both this and `impression_basis`. Tiers are different units with no exchange rate, so compare impressions within a tier (and for `sensor_measured`, within the same `basis_metric`), and plays and spend across tiers. Billing is unchanged: a CPM bills the row's total `impressions`, all tiers together. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`.", + "items": { + "$ref": "/schemas/core/impression-basis-breakdown-entry.json" + }, + "minItems": 2 + }, "venue_breakdown": { "type": "array", "description": "Per-venue performance breakdown", @@ -310,6 +355,19 @@ "type": "integer", "description": "Number of screens used at this venue", "minimum": 0 + }, + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Methodology tier of this venue's impressions, when it differs across venues of the row. Sellers MUST omit it on a venue whose plays were estimated on different tiers." + }, + "plays": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Plays at this venue, counted like the delivery row's `plays`: raw plays before any impression multiplier, not `loop_plays`. Each screen that played the spot counts one play, so a spot shown at once on three synchronized screens is three plays. A venue row carries no multiplier; its audience per play is `impressions / plays`." } }, "required": [ @@ -320,6 +378,11 @@ } } }, + "dependencies": { + "impression_basis_breakdown": { + "not": { "required": ["impression_basis"] } + } + }, "additionalProperties": true }, "ooh_metrics": { diff --git a/static/schemas/source/core/forecast-point.json b/static/schemas/source/core/forecast-point.json index 22cdc36c9bd..a26b5bc764e 100644 --- a/static/schemas/source/core/forecast-point.json +++ b/static/schemas/source/core/forecast-point.json @@ -29,6 +29,29 @@ "$ref": "/schemas/enums/availability-status.json", "description": "Bookability of the inventory this row describes, as of the forecast's generated_at. Most meaningful on rows with a time dimension in an availability forecast (forecast_range_unit 'availability'). This is a snapshot, not a hold: valid_until bounds freshness, and proposal finalization or purchase remains the commitment boundary. When omitted, the row makes no bookability claim. 'unavailable' rows may carry empty metrics." }, + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). On a DOOH point that forecasts `impressions` from `plays`, the methodology tier the forecast uses, when it is the same for every expected play. When the point covers plays expected on different tiers, including the fallback plays a sensor-equipped screen is expected to estimate on `seller_modeled` while its sensor is not reporting, sellers MUST omit it, never substituting `hybrid` or the majority tier, and report `impression_basis_breakdown`; a point never carries both. Lets forecast and delivery reconcile on the same declaration. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). The planning multiplier of a single-tier DOOH point: `metrics.impressions.mid / metrics.plays.mid`, rounded. The impressions are authoritative: a receiver MUST NOT reject a multiplier that differs from that ratio only by rounding. A point that reports `impression_basis_breakdown` SHOULD omit it and give each entry's planning multiplier instead: a multiplier blended across tiers mixes different units and misleads. A declaration, not a forecastable metric, so it sits outside `metrics`." + }, + "impression_basis_breakdown": { + "type": "array", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). For a DOOH point covering plays expected on different tiers, one entry per tier with the expected plays and impressions behind the point's midpoints: at least two entries, whose tiers MUST be distinct and whose `plays` and `impressions` MUST sum exactly to `metrics.plays.mid` and `metrics.impressions.mid`, which a point carrying a breakdown therefore carries. It SHOULD include the fallback the seller expects: the plays sensor-equipped screens are expected to estimate on `seller_modeled` while their sensor is not reporting. A point never carries both this and `impression_basis`. Tiers are different units with no exchange rate, so compare impressions within a tier (and for `sensor_measured`, within the same metric), and plays and spend across tiers.", + "items": { + "$ref": "/schemas/core/impression-basis-breakdown-entry.json" + }, + "minItems": 2 + }, "metrics": { "type": "object", "description": "Forecasted metric values. Keys are forecastable-metric enum values for delivery/engagement or event-type enum values for outcomes; vendor metrics use vendor_metric_values. Values are ForecastRange objects (low/mid/high). Use { \"mid\": value } for point estimates. When budget is present, these are the expected metrics at that spend level. When budget is omitted, these represent total available inventory — use spend to express the estimated cost. Additional keys beyond the documented properties are allowed for event-type values (purchase, lead, app_install, etc.).", @@ -125,5 +148,10 @@ } }, "required": ["metrics"], + "dependencies": { + "impression_basis_breakdown": { + "not": { "required": ["impression_basis"] } + } + }, "additionalProperties": true } diff --git a/static/schemas/source/core/impression-basis-breakdown-entry.json b/static/schemas/source/core/impression-basis-breakdown-entry.json new file mode 100644 index 00000000000..d582c58bd0e --- /dev/null +++ b/static/schemas/source/core/impression-basis-breakdown-entry.json @@ -0,0 +1,47 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/core/impression-basis-breakdown-entry.json", + "title": "Impression Basis Breakdown Entry", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). The plays of a DOOH row, or of a forecast point, whose audience was estimated on one tier, and the impressions they produced. A row that aggregates plays estimated on different tiers (sensor-equipped screens and screens without a sensor, or one screen whose sensor stopped reporting for part of the flight) lists one entry per tier instead of a row-level `impression_basis`: at least two entries, at most one per tier. In a delivery row the entries' `plays` and `impressions` sum exactly to the row's `plays` and `impressions`; in a forecast point they are the expected values behind the point's midpoints. Entries of different tiers are different units with no exchange rate.", + "type": "object", + "properties": { + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "description": "Tier the audience of these plays was estimated on." + }, + "plays": { + "type": "number", + "minimum": 0, + "description": "Plays whose audience was estimated on this tier. A number like the row's `plays`, so that a forecast's fractional expected values can sum exactly." + }, + "impressions": { + "type": "number", + "minimum": 0, + "description": "Impressions those plays produced. Authoritative: `audience_multiplier` is derived from it, not the other way round." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "description": "`impressions / plays` of these plays, rounded. A receiver MUST NOT reject a multiplier that differs from `impressions / plays` only by rounding. Optional on `currency_measured` entries." + }, + "ext": { "$ref": "/schemas/core/ext.json" } + }, + "required": ["impression_basis", "plays", "impressions"], + "additionalProperties": true, + "examples": [ + { + "impression_basis": "sensor_measured", + "plays": 21340, + "impressions": 397808, + "audience_multiplier": 18.64 + }, + { + "impression_basis": "seller_modeled", + "plays": 64732, + "impressions": 951545, + "audience_multiplier": 14.7 + } + ] +} diff --git a/static/schemas/source/core/placement.json b/static/schemas/source/core/placement.json index dbbf75af5f2..607c9c35966 100644 --- a/static/schemas/source/core/placement.json +++ b/static/schemas/source/core/placement.json @@ -70,7 +70,20 @@ "$ref": "/schemas/enums/dooh-motion-type.json", "description": "Physical motion capability of a visual DOOH screen, not an accepted-format declaration. Omit for audio-only placements." }, - "location": { "$ref": "#/definitions/ProductDoohLocation", "x-added-in": "3.3.0" } + "location": { "$ref": "#/definitions/ProductDoohLocation", "x-added-in": "3.3.0" }, + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Methodology tier the seller plans to estimate this placement's audience on, so a buyer can compare and filter products before buying. A product mixing screens on different tiers declares it per placement. Delivery reports the realised tiers, which can include the seller's model on a sensor-equipped screen while its sensor is not reporting. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). Planning audience per play for this placement: the `impressions / plays` the seller's forecasts use. Optional on `currency_measured` placements." + } }, "x-adcp-validation": { "verifier_constraints": { diff --git a/static/schemas/source/enums/impression-estimation-basis.json b/static/schemas/source/enums/impression-estimation-basis.json new file mode 100644 index 00000000000..dc03c27bf9e --- /dev/null +++ b/static/schemas/source/enums/impression-estimation-basis.json @@ -0,0 +1,21 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/enums/impression-estimation-basis.json", + "title": "Impression Estimation Basis", + "description": "Methodology tier of a DOOH audience figure: what kind of number `impressions` is when it is `plays × audience multiplier`. Tier, not provider and not instrument: the currency or seller model is named by `measurement_source`, the instrument by the vendor metric that `basis_metric` points to. A row whose plays were estimated on different tiers does not pick one of them, nor `hybrid`: it reports `impression_basis_breakdown` instead. Tiers are different units with no exchange rate: a sensor counts the people in its zone, a currency usually publishes a visibility-adjusted 'likely to see' figure, and a seller model is traffic-based. Compare impressions within a tier, and for `sensor_measured` within the same `basis_metric`, since a sensor counting people in front of a screen and a turnstile counting entries are different units too. Across tiers, compare plays and spend. Values MAY be added in later minor releases; a client on an older schema version SHOULD treat a value it does not recognize like `seller_modeled`.", + "type": "string", + "x-status": "experimental", + "x-added-in": "3.3.0", + "enum": [ + "currency_measured", + "seller_modeled", + "sensor_measured", + "hybrid" + ], + "enumDescriptions": { + "currency_measured": "The published estimate of an audience-measurement currency for the unit and period, named by `measurement_source`. Applies whether or not the currency calibrates its own model with sensors.", + "seller_modeled": "The seller's own model: a traffic study, a venue-attendance factor, historical footfall, or an audience figure the seller declares per screen or per hour. Also the tier of the plays a sensor-equipped screen estimates while its sensor is not reporting.", + "sensor_measured": "Audience observed at play time by an on-site sensor (presence detection, people counting, WiFi or BLE presence, turnstile, ticketing). Measured, not modeled, though the sensor has its own error. The sensor's figure SHOULD be reported as the vendor metric `basis_metric` points to.", + "hybrid": "A seller-owned model calibrated by sensors on the seller's own screens, whoever supplies them, for example sensor counts on some screens scaling a seller traffic study across a network. Never a published currency figure, and never a mere mix of plays estimated on different tiers, which `impression_basis_breakdown` reports. Rows on this tier SHOULD carry `calculation_notes`." + } +} diff --git a/static/schemas/source/index.json b/static/schemas/source/index.json index 3b68e2cabd7..b94344ef899 100644 --- a/static/schemas/source/index.json +++ b/static/schemas/source/index.json @@ -329,6 +329,10 @@ "$ref": "/schemas/core/delivery-metrics.json", "description": "Standard delivery metrics for reporting" }, + "impression-basis-breakdown-entry": { + "$ref": "/schemas/core/impression-basis-breakdown-entry.json", + "description": "Experimental. The plays of a DOOH row or forecast point estimated on one impression basis tier, and the impressions they produced" + }, "delivery-metric-aggregate": { "$ref": "/schemas/core/delivery-metric-aggregate.json", "description": "Cross-buy delivery aggregate partitioned by metric scope and qualifier" @@ -1614,6 +1618,10 @@ "$ref": "/schemas/enums/delivery-projection-basis.json", "description": "Class of method behind a delivery projection (trailing_daily_avg, trailing_hourly_avg, platform_model, seller_defined)" }, + "impression-estimation-basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "description": "Methodology tier of a DOOH audience figure (currency_measured, seller_modeled, sensor_measured, hybrid)" + }, "forecast-method": { "$ref": "/schemas/enums/forecast-method.json", "description": "Method used to produce a delivery forecast (estimate, modeled, guaranteed)" diff --git a/tests/dooh-impression-basis.test.cjs b/tests/dooh-impression-basis.test.cjs new file mode 100644 index 00000000000..55db5a5bac7 --- /dev/null +++ b/tests/dooh-impression-basis.test.cjs @@ -0,0 +1,292 @@ +const fs = require("fs"); +const path = require("path"); +const Ajv = require("ajv"); +const addFormats = require("ajv-formats"); +const { describe, it, before } = require("node:test"); +const assert = require("node:assert/strict"); + +// DOOH impression basis (media_buy.dooh_impression_basis, RFC #7253): discovery, forecast and +// delivery payloads of a product mixing sensor-equipped screens and screens without a sensor. + +const ROOT = path.join(__dirname, ".."); +const SCHEMA_ROOT = path.join(ROOT, "static", "schemas", "source"); +const FIXTURES = path.join(__dirname, "fixtures", "dooh-impression-basis"); +const FEATURE_ID = "media_buy.dooh_impression_basis"; + +function readSchema(uri) { + return JSON.parse(fs.readFileSync(path.join(SCHEMA_ROOT, uri.slice("/schemas/".length)), "utf8")); +} + +function fixture(name) { + return JSON.parse(fs.readFileSync(path.join(FIXTURES, name), "utf8")); +} + +const clone = (value) => JSON.parse(JSON.stringify(value)); + +// A declared multiplier is the counts' ratio, rounded. +function assertMultiplier(multiplier, impressions, plays, where) { + assert.ok(plays > 0, `${where}: plays`); + // impressions is authoritative; the multiplier is impressions / plays rounded to its own decimals. + const ratio = impressions / plays; + const decimals = (String(multiplier).split(".")[1] ?? "").length; + assert.ok(Math.abs(ratio - multiplier) <= 0.5 * 10 ** -decimals + 1e-9, `${where}: ${impressions} / ${plays} = ${ratio}, declared ${multiplier}`); +} + +// Breakdown entries: at least two, one per tier, summing exactly to the row's counts, each +// multiplier consistent. Draft-07 cannot count matches, so distinct tiers are checked here. +function assertBreakdown(entries, plays, impressions, where) { + const tiers = entries.map((entry) => entry.impression_basis); + assert.ok(entries.length >= 2, `${where}: at least two entries`); + assert.equal(new Set(tiers).size, tiers.length, `${where}: one entry per tier`); + assert.equal(entries.reduce((sum, entry) => sum + entry.plays, 0), plays, `${where}: plays sum`); + assert.equal(entries.reduce((sum, entry) => sum + entry.impressions, 0), impressions, `${where}: impressions sum`); + for (const entry of entries) + if (entry.audience_multiplier !== undefined) + assertMultiplier(entry.audience_multiplier, entry.impressions, entry.plays, `${where} ${entry.impression_basis}`); +} + +// A row's counts per tier: its breakdown entries, or its single tier holding all its counts. +function tierCounts(dooh, plays, impressions) { + const entries = dooh.impression_basis_breakdown ?? [{ impression_basis: dooh.impression_basis, plays, impressions }]; + return Object.fromEntries(entries.map((entry) => [entry.impression_basis, { plays: entry.plays, impressions: entry.impressions }])); +} + +// Each tier entry of a parent row is the sum of its children's entries for that tier. +function assertParentSumsChildren(parent, children, where) { + const sum = {}; + for (const child of children) + for (const [tier, counts] of Object.entries(tierCounts(child.dooh_metrics, child.plays, child.impressions))) { + sum[tier] ??= { plays: 0, impressions: 0 }; + sum[tier].plays += counts.plays; + sum[tier].impressions += counts.impressions; + } + assert.deepEqual(tierCounts(parent.dooh_metrics, parent.plays, parent.impressions), sum, `${where}: tiers sum over children`); +} + +// Every delivery row: either a single tier or a breakdown, a consistent multiplier (none blended +// across tiers), and a basis_metric that joins a vendor_metric_values row of the same object. +function assertDeliveryRow(row, where) { + const dooh = row.dooh_metrics; + assert.ok(dooh, `${where}: dooh_metrics`); + assert.ok((dooh.impression_basis === undefined) !== (dooh.impression_basis_breakdown === undefined), `${where}: impression_basis xor impression_basis_breakdown`); + if (dooh.audience_multiplier !== undefined) + assertMultiplier(dooh.audience_multiplier, row.impressions, row.plays, where); + if (dooh.impression_basis_breakdown) { + assertBreakdown(dooh.impression_basis_breakdown, row.plays, row.impressions, where); + assert.equal(dooh.audience_multiplier, undefined, `${where}: no multiplier blended across tiers`); + } + if (dooh.basis_metric) { + const joined = (row.vendor_metric_values ?? []).find((value) => + value.vendor.domain === dooh.basis_metric.vendor.domain && value.metric_id === dooh.basis_metric.metric_id); + assert.ok(joined, `${where}: basis_metric joins a vendor_metric_values row`); + const sensor = dooh.impression_basis_breakdown?.find((entry) => entry.impression_basis === "sensor_measured"); + if (sensor) { + assert.equal(joined.measurable_plays, sensor.plays, `${where}: the sensor covers the sensor_measured plays`); + assert.equal(joined.value, sensor.impressions, `${where}: the persons counted are the sensor_measured impressions`); + } + } +} + +describe("DOOH impression basis schemas", () => { + it("adds an experimental four-tier enum", () => { + const basis = readSchema("/schemas/enums/impression-estimation-basis.json"); + assert.equal(basis["x-status"], "experimental"); + assert.equal(basis["x-added-in"], "3.3.0"); + assert.deepEqual(basis.enum, ["currency_measured", "seller_modeled", "sensor_measured", "hybrid"]); + assert.deepEqual(Object.keys(basis.enumDescriptions), basis.enum); + }); + + it("marks every new property experimental under one feature id", () => { + const dooh = readSchema("/schemas/core/delivery-metrics.json").properties.dooh_metrics; + const venue = dooh.properties.venue_breakdown.items.properties; + const point = readSchema("/schemas/core/forecast-point.json").properties; + const product = readSchema("/schemas/core/placement.json").definitions.ProductDoohPlacementAttributes.properties; + const canonical = readSchema("/schemas/core/canonical-placement.json").definitions.CanonicalDoohPlacementAttributes.properties; + const canonicalPoint = readSchema("/schemas/core/canonical-forecast-point.json").properties; + const nodes = [ + dooh.properties.impression_basis, dooh.properties.audience_multiplier, dooh.properties.basis_metric, + dooh.properties.impression_basis_breakdown, venue.impression_basis, venue.plays, + point.impression_basis, point.audience_multiplier, point.impression_basis_breakdown, + canonicalPoint.impression_basis, canonicalPoint.audience_multiplier, canonicalPoint.impression_basis_breakdown, + product.impression_basis, product.audience_multiplier, canonical.impression_basis, canonical.audience_multiplier, + readSchema("/schemas/core/impression-basis-breakdown-entry.json"), + ]; + for (const node of nodes) { + assert.equal(node["x-status"], "experimental"); + assert.equal(node["x-added-in"], "3.3.0"); + assert.ok(node.description.startsWith(`Experimental (${FEATURE_ID}).`), node.description); + } + }); + + it("leaves the stable dooh_metrics block and the experimental ooh_metrics block as they were", () => { + const metrics = readSchema("/schemas/core/delivery-metrics.json").properties; + assert.equal(metrics.dooh_metrics["x-status"], undefined); + assert.equal(metrics.dooh_metrics.additionalProperties, true); + assert.deepEqual(metrics.ooh_metrics.properties.estimation_basis.enum, ["currency_measured", "seller_modeled"]); + }); + + it("keeps the multiplier out of the forecastable metrics", () => { + const point = readSchema("/schemas/core/forecast-point.json"); + assert.equal(point.properties.metrics.properties.audience_multiplier, undefined); + assert.ok(!readSchema("/schemas/enums/forecastable-metric.json").enum.includes("audience_multiplier")); + }); + + it("requires two or more entries and never a breakdown beside a row-level tier", () => { + const dooh = readSchema("/schemas/core/delivery-metrics.json").properties.dooh_metrics; + const point = readSchema("/schemas/core/forecast-point.json"); + const canonicalPoint = readSchema("/schemas/core/canonical-forecast-point.json"); + const exclusion = { impression_basis_breakdown: { not: { required: ["impression_basis"] } } }; + for (const schema of [dooh, point, canonicalPoint]) { + assert.equal(schema.properties.impression_basis_breakdown.minItems, 2); + assert.deepEqual(schema.dependencies, exclusion); + } + }); + + it("lists the feature id in the experimental-status table", () => { + const doc = fs.readFileSync(path.join(ROOT, "docs", "reference", "experimental-status.mdx"), "utf8"); + assert.match(doc, /^\| `media_buy\.dooh_impression_basis` \|/m); + }); +}); + +describe("DOOH impression basis fixtures: a product mixing sensor-measured and seller-modeled screens", () => { + let validateProduct, validateCanonicalProduct, validateForecast, validateCanonicalForecast, validateDelivery, validateEntry; + + before(async () => { + const ajv = new Ajv({ allErrors: true, strict: false, loadSchema: async (ref) => readSchema(ref) }); + addFormats(ajv); + // A schema another one already pulled in is compiled from the instance, not added twice. + const compile = async (id) => ajv.getSchema(id) ?? ajv.compileAsync(readSchema(id)); + validateProduct = await compile("/schemas/core/product.json"); + validateCanonicalProduct = await compile("/schemas/core/canonical-product.json"); + validateForecast = await compile("/schemas/core/delivery-forecast.json"); + validateCanonicalForecast = await compile("/schemas/core/canonical-delivery-forecast.json"); + validateDelivery = await compile("/schemas/media-buy/get-media-buy-delivery-response.json"); + validateEntry = await compile("/schemas/core/impression-basis-breakdown-entry.json"); + }); + + it("discovery: each placement declares its planned tier and multiplier", () => { + const product = fixture("discovery-product.json"); + assert.equal(validateProduct(product), true, JSON.stringify(validateProduct.errors, null, 2)); + // The same product in list_products. + assert.equal(validateCanonicalProduct(product), true, JSON.stringify(validateCanonicalProduct.errors, null, 2)); + const tiers = product.placements.map((placement) => placement.dooh_placement_attributes.impression_basis); + assert.deepEqual(tiers, ["sensor_measured", "seller_modeled"]); + }); + + // The concourse's sensor screens are expected to fall back on 30% of their plays, the share + // of fallback plays on sensor screens in the adopter's production data (9% of 30%). + it("forecast: the expected split, fallback included, reconciles with the midpoints", () => { + const forecast = fixture("forecast.json"); + assert.equal(validateForecast(forecast), true, JSON.stringify(validateForecast.errors, null, 2)); + // The same forecast in list_products and the proposal tasks. + assert.equal(validateCanonicalForecast(forecast), true, JSON.stringify(validateCanonicalForecast.errors, null, 2)); + for (const point of forecast.points) { + const plays = point.metrics.plays.mid; + const impressions = point.metrics.impressions.mid; + assertBreakdown(point.impression_basis_breakdown, plays, impressions, point.label); + assert.equal(point.audience_multiplier, undefined, `${point.label}: no multiplier blended across tiers`); + } + const [sensor, modeled] = forecast.points[0].impression_basis_breakdown; + const platformPlays = 58300; + assert.equal(sensor.plays / (sensor.plays + modeled.plays - platformPlays), 0.7, "concourse: 70% sensor plays, 30% fallback"); + }); + + it("forecast: fractional expected counts can sum exactly", () => { + const forecast = fixture("forecast.json"); + const point = forecast.points[0]; + point.metrics.plays.mid = 1000; + point.metrics.impressions.mid = 14400.5; + point.impression_basis_breakdown = [ + { impression_basis: "sensor_measured", plays: 500, impressions: 7200.25 }, + { impression_basis: "seller_modeled", plays: 500, impressions: 7200.25 }, + ]; + for (const validate of [validateForecast, validateCanonicalForecast]) + assert.equal(validate(forecast), true, JSON.stringify(validate.errors, null, 2)); + assertBreakdown(point.impression_basis_breakdown, 1000, 14400.5, point.label); + }); + + it("delivery: totals, package and placements carry a consistent basis, including a sensor screen that fell back", () => { + const delivery = fixture("delivery.json"); + assert.equal(validateDelivery(delivery), true, JSON.stringify(validateDelivery.errors, null, 2)); + for (const buy of delivery.media_buy_deliveries) { + assertDeliveryRow(buy.totals, "totals"); + assertParentSumsChildren(buy.totals, buy.by_package, "totals"); + for (const pkg of buy.by_package) { + assertDeliveryRow(pkg, pkg.package_id); + for (const placement of pkg.by_placement) + assertDeliveryRow(placement, placement.placement_id); + assertParentSumsChildren(pkg, pkg.by_placement, pkg.package_id); + } + } + const fallback = delivery.media_buy_deliveries[0].by_package[0].by_placement[0].dooh_metrics.impression_basis_breakdown; + assert.deepEqual(fallback.map((entry) => entry.impression_basis), ["sensor_measured", "seller_modeled"]); + }); + + describe("rejects", () => { + const placementRow = () => fixture("delivery.json").media_buy_deliveries[0].by_package[0].by_placement[0]; + // The keywords a payload fails on, so that a vector cannot pass for the wrong reason. + const failures = (validate, data) => (validate(data) ? [] : validate.errors.map((error) => error.keyword)); + const assertFailsOn = (keywords, expected) => + assert.ok(keywords.includes(expected), `expected ${expected}, got ${keywords.join(", ") || "a valid payload"}`); + const reject = (mutate) => { + const delivery = fixture("delivery.json"); + mutate(delivery.media_buy_deliveries[0].by_package[0].by_placement[0].dooh_metrics); + return failures(validateDelivery, delivery); + }; + + it("an unknown tier", () => { + assertFailsOn(reject((dooh) => { dooh.impression_basis_breakdown[0].impression_basis = "panel_measured"; }), "enum"); + }); + + it("a negative multiplier", () => { + // On the single-tier platform row, which may carry a multiplier. + const delivery = fixture("delivery.json"); + delivery.media_buy_deliveries[0].by_package[0].by_placement[1].dooh_metrics.audience_multiplier = -1; + assertFailsOn(failures(validateDelivery, delivery), "minimum"); + }); + + it("a breakdown entry without its tier", () => { + assertFailsOn(reject((dooh) => { delete dooh.impression_basis_breakdown[1].impression_basis; }), "required"); + }); + + it("a breakdown with fewer than two entries", () => { + assertFailsOn(reject((dooh) => { dooh.impression_basis_breakdown = [dooh.impression_basis_breakdown[0]]; }), "minItems"); + assertFailsOn(reject((dooh) => { dooh.impression_basis_breakdown = []; }), "minItems"); + const point = fixture("forecast.json"); + point.points[0].impression_basis_breakdown.pop(); + assertFailsOn(failures(validateForecast, point), "minItems"); + assertFailsOn(failures(validateCanonicalForecast, point), "minItems"); + }); + + it("a breakdown repeating a tier", () => { + // Draft-07 cannot count the entries of one tier: the rule is prose, checked here. + const row = placementRow(); + const entries = row.dooh_metrics.impression_basis_breakdown.map((entry) => ({ ...entry, impression_basis: "sensor_measured" })); + assert.throws(() => assertBreakdown(entries, row.plays, row.impressions, row.placement_id), /one entry per tier/); + }); + + it("a row carrying both a tier and a breakdown", () => { + assertFailsOn(reject((dooh) => { dooh.impression_basis = "sensor_measured"; }), "not"); + const forecast = fixture("forecast.json"); + forecast.points[0].impression_basis = "seller_modeled"; + assertFailsOn(failures(validateForecast, forecast), "not"); + assertFailsOn(failures(validateCanonicalForecast, forecast), "not"); + }); + + it("a basis_metric without its metric_id", () => { + assertFailsOn(reject((dooh) => { delete dooh.basis_metric.metric_id; }), "required"); + }); + + it("a breakdown entry without its counts", () => { + const entry = clone(placementRow().dooh_metrics.impression_basis_breakdown[0]); + delete entry.plays; + assertFailsOn(failures(validateEntry, entry), "required"); + }); + + it("an unknown planned tier on a placement", () => { + const product = fixture("discovery-product.json"); + product.placements[0].dooh_placement_attributes.impression_basis = "panel_modeled"; + assertFailsOn(failures(validateProduct, product), "enum"); + }); + }); +}); diff --git a/tests/fixtures/dooh-impression-basis/delivery.json b/tests/fixtures/dooh-impression-basis/delivery.json new file mode 100644 index 00000000000..ae72a47181e --- /dev/null +++ b/tests/fixtures/dooh-impression-basis/delivery.json @@ -0,0 +1,76 @@ +{ + "status": "completed", + "reporting_period": { + "start": "2026-10-05T00:00:00Z", + "end": "2026-11-04T00:00:00Z" + }, + "currency": "USD", + "media_buy_deliveries": [{ + "media_buy_id": "mb_acme_outdoor_metro", + "status": "active", + "totals": { + "impressions": 1349353, + "spend": 10794.82, + "plays": 86072, + "dooh_metrics": { + "screens_used": 256, + "impression_basis_breakdown": [ + { "impression_basis": "sensor_measured", "plays": 21340, "impressions": 397808, "audience_multiplier": 18.64 }, + { "impression_basis": "seller_modeled", "plays": 64732, "impressions": 951545, "audience_multiplier": 14.7 } + ] + } + }, + "by_package": [{ + "package_id": "pkg_metro_loop", + "pricing_model": "cpm", + "rate": 8, + "currency": "USD", + "impressions": 1349353, + "spend": 10794.82, + "plays": 86072, + "dooh_metrics": { + "screens_used": 256, + "impression_basis_breakdown": [ + { "impression_basis": "sensor_measured", "plays": 21340, "impressions": 397808, "audience_multiplier": 18.64 }, + { "impression_basis": "seller_modeled", "plays": 64732, "impressions": 951545, "audience_multiplier": 14.7 } + ] + }, + "by_placement": [ + { + "placement_id": "concourse_screens", + "impressions": 510333, + "spend": 4082.66, + "plays": 27805, + "dooh_metrics": { + "screens_used": 85, + "impression_basis_breakdown": [ + { "impression_basis": "sensor_measured", "plays": 21340, "impressions": 397808, "audience_multiplier": 18.64 }, + { "impression_basis": "seller_modeled", "plays": 6465, "impressions": 112525, "audience_multiplier": 17.41 } + ], + "basis_metric": { "vendor": { "domain": "metro-media.example" }, "metric_id": "people_counted" }, + "calculation_notes": "Sensor-equipped screens: the audience counted at each play. Plays while a screen's sensor had not reported for 24 hours use the screen's declared hourly audience." + }, + "vendor_metric_values": [{ + "vendor": { "domain": "metro-media.example" }, + "metric_id": "people_counted", + "value": 397808, + "unit": "persons", + "measurable_plays": 21340, + "vendor_relationship": "first_party" + }] + }, + { + "placement_id": "platform_screens", + "impressions": 839020, + "spend": 6712.16, + "plays": 58267, + "dooh_metrics": { + "screens_used": 171, + "impression_basis": "seller_modeled", + "audience_multiplier": 14.4 + } + } + ] + }] + }] +} diff --git a/tests/fixtures/dooh-impression-basis/discovery-product.json b/tests/fixtures/dooh-impression-basis/discovery-product.json new file mode 100644 index 00000000000..7ceadae6868 --- /dev/null +++ b/tests/fixtures/dooh-impression-basis/discovery-product.json @@ -0,0 +1,72 @@ +{ + "product_id": "metro_concourse_and_platform_loop", + "name": "Metro concourse and platform loop", + "description": "Landscape screens across fictional metro concourses, where on-site sensors count the audience at each play, and platforms, where the seller declares an hourly audience per screen.", + "channels": ["dooh"], + "delivery_type": "non_guaranteed", + "publisher_properties": [{ + "publisher_domain": "metro-media.example", + "selection_type": "by_tag", + "property_tags": ["transit_venues"] + }], + "placements": [ + { + "kind": "seller_inline", + "publisher_domain": "metro-media.example", + "placement_id": "concourse_screens", + "name": "Concourse screens", + "mode": "included", + "tags": ["transit", "concourse"], + "dooh_placement_attributes": { + "slot_duration_seconds": 10, + "loop_duration_seconds": 120, + "screen_resolution": { "width": 1920, "height": 1080 }, + "motion": "full_motion", + "impression_basis": "sensor_measured", + "audience_multiplier": 18.6 + } + }, + { + "kind": "seller_inline", + "publisher_domain": "metro-media.example", + "placement_id": "platform_screens", + "name": "Platform screens", + "mode": "included", + "tags": ["transit", "platform"], + "dooh_placement_attributes": { + "slot_duration_seconds": 10, + "loop_duration_seconds": 120, + "screen_resolution": { "width": 1920, "height": 1080 }, + "motion": "full_motion", + "impression_basis": "seller_modeled", + "audience_multiplier": 14.4 + } + } + ], + "format_options": [{ + "format_option_id": "landscape_image_1920x1080", + "format_kind": "image", + "params": { + "width": 1920, + "height": 1080, + "max_file_size_kb": 10240 + } + }], + "pricing_options": [{ + "pricing_option_id": "metro_loop_cpm", + "pricing_model": "cpm", + "currency": "USD", + "fixed_price": 8 + }], + "reporting_capabilities": { + "available_reporting_frequencies": ["daily"], + "expected_delay_minutes": 240, + "timezone": "UTC", + "supports_webhooks": false, + "available_metrics": ["impressions", "spend", "plays", "dooh_metrics"], + "vendor_metrics": [ + { "vendor": { "domain": "metro-media.example" }, "metric_id": "people_counted" } + ], + "date_range_support": "date_range" + } +} diff --git a/tests/fixtures/dooh-impression-basis/forecast.json b/tests/fixtures/dooh-impression-basis/forecast.json new file mode 100644 index 00000000000..a23fe58b18c --- /dev/null +++ b/tests/fixtures/dooh-impression-basis/forecast.json @@ -0,0 +1,19 @@ +{ + "points": [{ + "label": "Available from 2026-11-09 to 2026-11-15", + "metrics": { + "plays": { "mid": 86100 }, + "impressions": { "mid": 1346592 }, + "spend": { "mid": 10772.74 } + }, + "impression_basis_breakdown": [ + { "impression_basis": "sensor_measured", "plays": 19460, "impressions": 361956, "audience_multiplier": 18.6 }, + { "impression_basis": "seller_modeled", "plays": 66640, "impressions": 984636, "audience_multiplier": 14.78 } + ] + }], + "forecast_range_unit": "availability", + "method": "modeled", + "currency": "USD", + "generated_at": "2026-11-04T08:00:00Z", + "valid_until": "2026-11-04T20:00:00Z" +} diff --git a/tests/x-added-in-3-3-sweep.test.cjs b/tests/x-added-in-3-3-sweep.test.cjs index d598624cec8..516a59d19b1 100644 --- a/tests/x-added-in-3-3-sweep.test.cjs +++ b/tests/x-added-in-3-3-sweep.test.cjs @@ -44,6 +44,9 @@ const WHOLE_FILE_3_3 = [ 'enums/reporting-dimension.json', 'core/match-key.json', 'enums/match-key-use.json', + // DOOH impression basis (media_buy.dooh_impression_basis, RFC #7253). + 'enums/impression-estimation-basis.json', + 'core/impression-basis-breakdown-entry.json', ]; const PROPERTIES_3_3 = [ @@ -75,6 +78,23 @@ const PROPERTIES_3_3 = [ ['core/canonical-product.json', ['properties', 'dooh_inventory_summary']], ['core/product.json', ['properties', 'dooh_inventory_summary']], ['core/delivery-metrics.json', ['properties', 'print_metrics']], + // DOOH impression basis (media_buy.dooh_impression_basis, RFC #7253). + ['core/delivery-metrics.json', ['properties', 'dooh_metrics', 'properties', 'impression_basis']], + ['core/delivery-metrics.json', ['properties', 'dooh_metrics', 'properties', 'audience_multiplier']], + ['core/delivery-metrics.json', ['properties', 'dooh_metrics', 'properties', 'basis_metric']], + ['core/delivery-metrics.json', ['properties', 'dooh_metrics', 'properties', 'impression_basis_breakdown']], + ['core/delivery-metrics.json', ['properties', 'dooh_metrics', 'properties', 'venue_breakdown', 'items', 'properties', 'impression_basis']], + ['core/delivery-metrics.json', ['properties', 'dooh_metrics', 'properties', 'venue_breakdown', 'items', 'properties', 'plays']], + ['core/forecast-point.json', ['properties', 'impression_basis']], + ['core/forecast-point.json', ['properties', 'audience_multiplier']], + ['core/forecast-point.json', ['properties', 'impression_basis_breakdown']], + ['core/canonical-forecast-point.json', ['properties', 'impression_basis']], + ['core/canonical-forecast-point.json', ['properties', 'audience_multiplier']], + ['core/canonical-forecast-point.json', ['properties', 'impression_basis_breakdown']], + ['core/placement.json', ['definitions', 'ProductDoohPlacementAttributes', 'properties', 'impression_basis']], + ['core/placement.json', ['definitions', 'ProductDoohPlacementAttributes', 'properties', 'audience_multiplier']], + ['core/canonical-placement.json', ['definitions', 'CanonicalDoohPlacementAttributes', 'properties', 'impression_basis']], + ['core/canonical-placement.json', ['definitions', 'CanonicalDoohPlacementAttributes', 'properties', 'audience_multiplier']], ['core/reporting-webhook.json', ['properties', 'operation_id']], ['governance/sync-plans-request.json', ['properties', 'plans', 'items', 'properties', 'budget', 'properties', 'periods']], ['protocol/get-adcp-capabilities-response.json', ['properties', 'governance', 'properties', 'supports_budget_periods']],