From 67b306841e9fd76b1493f45ab3eab6c1e909e58f Mon Sep 17 00:00:00 2001 From: Aymeric Le Corre Date: Wed, 4 Nov 2026 14:13:37 +0100 Subject: [PATCH 1/5] feat(schema): experimental DOOH impression basis (RFC #7253) Shared impression-estimation-basis tier enum; on DOOH delivery rows the tier, the declared audience multiplier, a basis_metric pointer to the sensor's vendor metric row, and a per-tier breakdown for rows that mix tiers; the same declaration and the planning multiplier on forecast points and DOOH placement attributes. Experimental under media_buy.dooh_impression_basis, with fixtures of a product mixing sensor-measured and seller-modeled screens. --- .changeset/dooh-impression-basis.md | 5 + docs/creative/channels/dooh.mdx | 36 ++++ .../media-buys/optimization-reporting.mdx | 3 +- .../product-discovery/media-products.mdx | 2 + docs/reference/experimental-status.mdx | 1 + package.json | 2 +- .../source/core/canonical-placement.json | 15 +- .../schemas/source/core/delivery-metrics.json | 58 +++++ .../schemas/source/core/forecast-point.json | 23 ++ .../impression-basis-breakdown-entry.json | 47 ++++ static/schemas/source/core/placement.json | 15 +- .../enums/impression-estimation-basis.json | 21 ++ static/schemas/source/index.json | 4 + tests/dooh-impression-basis.test.cjs | 203 ++++++++++++++++++ .../dooh-impression-basis/delivery.json | 79 +++++++ .../discovery-product.json | 72 +++++++ .../dooh-impression-basis/forecast.json | 20 ++ tests/x-added-in-3-3-sweep.test.cjs | 17 ++ 18 files changed, 619 insertions(+), 4 deletions(-) create mode 100644 .changeset/dooh-impression-basis.md create mode 100644 static/schemas/source/core/impression-basis-breakdown-entry.json create mode 100644 static/schemas/source/enums/impression-estimation-basis.json create mode 100644 tests/dooh-impression-basis.test.cjs create mode 100644 tests/fixtures/dooh-impression-basis/delivery.json create mode 100644 tests/fixtures/dooh-impression-basis/discovery-product.json create mode 100644 tests/fixtures/dooh-impression-basis/forecast.json diff --git a/.changeset/dooh-impression-basis.md b/.changeset/dooh-impression-basis.md new file mode 100644 index 00000000000..20cac47b261 --- /dev/null +++ b/.changeset/dooh-impression-basis.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": minor +--- + +Add the experimental DOOH impression basis (feature id `media_buy.dooh_impression_basis`, RFC #7253): a shared `enums/impression-estimation-basis.json` tier enum (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`) that says what kind of number a DOOH `impressions` figure (`plays × audience multiplier`) is. Delivery rows carry `dooh_metrics.impression_basis`, the declared `audience_multiplier`, a `basis_metric` pointer to the `vendor_metric_values[]` row a sensor audience comes from, and, for a row whose plays were estimated on different tiers, an `impression_basis_breakdown[]` (`core/impression-basis-breakdown-entry.json`) whose entries sum to the row's plays and impressions; `venue_breakdown[]` rows may carry the tier and multiplier. Forecast points carry the same declaration and the planning multiplier outside `metrics`, and product and canonical `dooh_placement_attributes` the planned tier and multiplier. `hybrid` is a seller model calibrated by the seller's own sensors, never a published currency nor a mix of tiers. All fields are optional; `ooh_metrics.estimation_basis` and the closed canonical forecast schemas are unchanged. diff --git a/docs/creative/channels/dooh.mdx b/docs/creative/channels/dooh.mdx index cc7cb21893d..90cdb60755d 100644 --- a/docs/creative/channels/dooh.mdx +++ b/docs/creative/channels/dooh.mdx @@ -256,6 +256,42 @@ 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`: + +- **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. +- **Forecast.** A forecast point carries the planning `audience_multiplier`, so `metrics.impressions.mid ≈ metrics.plays.mid × audience_multiplier`, and either the point's single `impression_basis` or an `impression_basis_breakdown` of the expected plays per tier. +- **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, one entry per tier summing to the row's `plays` and `impressions`. 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. + +`hybrid` is a seller model calibrated by the seller's own sensors, never a published currency figure and never a mix of plays on different tiers, which the breakdown reports. A placement row of a product mixing both tiers: + +```json +{ + "placement_id": "concourse_screens", + "impressions": 510333, + "spend": 4082.66, + "plays": 27805, + "dooh_metrics": { + "screens_used": 85, + "audience_multiplier": 18.35, + "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 b15fe743f9b..eec70734d88 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 cb75a5ee9c9..8b0cf339fcc 100644 --- a/docs/media-buy/product-discovery/media-products.mdx +++ b/docs/media-buy/product-discovery/media-products.mdx @@ -457,6 +457,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 fe38ebb6706..a6dd459d898 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -151,6 +151,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` / `audience_multiplier` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/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`), with one production adopter so far, whose network mixes sensor-measured and seller-modeled screens. The boundary of `hybrid` (a seller model calibrated by the seller's sensors, never a published currency and never a mix of plays on different tiers), the breakdown that reports such a mix, whether the multiplier is disclosed on `currency_measured` rows, and whether `impression_basis` becomes required for the `sales-dooh` claim are open for the working group. `ooh_metrics.estimation_basis` keeps its inline two-value enum. The closed canonical forecast schemas do not carry these fields in 3.x (DR-0036). | | `media_buy.audience_evidence_targets` | The `target_audiences[]` field, a sibling of `audience_evidence_requirements` on `core/product-filters.json` (`get_products` `filters`) and `media-buy/package-request.json` (`create_media_buy` packages), and its item schema `core/audience-evidence-target.json` (`audience`, `relationship`, `minimum_value`) ([RFC #8125](https://github.com/adcontextprotocol/adcp/issues/8125)). See [audience evidence requirements](/docs/media-buy/task-reference/get_products#audience-evidence-requirements). | Structured soft and hard audience preference over `audience_evidence`, with a single adopter so far and no field-testing across parties yet. The exact-match audience rule (no superset, subset, or adjusted-share matching), AND across targets, the lack of a baseline on `index` targets, the `minimum_value` units, the `maxItems` bound, and whether per-target satisfaction is reported in `audience_evidence_selections` may change. The field is a sibling rather than a member of the closed `audience_evidence_requirements` schemas, because a minor release never changes a closed schema. The closed `buy_products` purchase schemas and the closed `list_products` `offer_filters` do not carry it in 3.3; it arrives there in 4.0 (see the [4.0 compatibility check](/docs/reference/migration/v4-compatibility#purchase_target_audiences_required_in_4_0)), together with the purchase-snapshot echo. The `enums/audience-evidence-relationship.json` file carries the same values as the stable 3.2 `audience_evidence.relationship` enum, which stays inline and unchanged. Sellers that evaluate `target_audiences` declare the id; a seller that does not declare it MUST fail a `required` request with `UNSUPPORTED_FEATURE` rather than ignore it. | | `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/package.json b/package.json index e128a839e10..78f3c4ed9bd 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/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/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/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.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/price-adjustments-vectors.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-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/structured-package-refine.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/collection-catalog.test.cjs tests/collection-copies-vectors.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/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/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/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.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/price-adjustments-vectors.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/dooh-impression-basis.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-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/structured-package-refine.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/collection-catalog.test.cjs tests/collection-copies-vectors.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-placement.json b/static/schemas/source/core/canonical-placement.json index 74dceba7ce7..936eb34248c 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. Delivery reports the realised tiers." + }, + "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." + } }, "x-adcp-validation": { "verifier_constraints": { diff --git a/static/schemas/source/core/delivery-metrics.json b/static/schemas/source/core/delivery-metrics.json index 02e48ccc1d9..4a1cc842a58 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 aggregates plays estimated on different tiers, omit it and report `impression_basis_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 effective `impressions / plays`, declared rather than inferred, so a verifier can check `impressions ≈ plays × audience_multiplier` and a buyer can compare rows. 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, for currencies whose terms prohibit disclosing it." + }, + "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 of the same object 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 `vendor_metric_values[]` row MUST be present in the same object.", + "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 screen that fell back to the seller's model while its sensor was not reporting — one entry per tier, whose `plays` and `impressions` sum to the row's. A row reports either `impression_basis` or this breakdown. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`.", + "items": { + "$ref": "/schemas/core/impression-basis-breakdown-entry.json" + }, + "minItems": 1 + }, "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." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (media_buy.dooh_impression_basis). This venue's effective `impressions / loop_plays`, declared rather than inferred." } }, "required": [ diff --git a/static/schemas/source/core/forecast-point.json b/static/schemas/source/core/forecast-point.json index 22cdc36c9bd..483c0788497 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, omit it and report `impression_basis_breakdown`. 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 DOOH point: the `impressions / plays` the forecast applies, so `metrics.impressions.mid ≈ metrics.plays.mid × audience_multiplier`. 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. A point reports either `impression_basis` or this breakdown.", + "items": { + "$ref": "/schemas/core/impression-basis-breakdown-entry.json" + }, + "minItems": 1 + }, "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.).", 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..440bf0425f5 --- /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 most one entry per tier. In a delivery row the entries' `plays` and `impressions` sum to the row's `plays` and `impressions`; in a forecast point they are the expected values behind the point's midpoints.", + "type": "object", + "properties": { + "impression_basis": { + "$ref": "/schemas/enums/impression-estimation-basis.json", + "description": "Tier the audience of these plays was estimated on." + }, + "plays": { + "type": "integer", + "minimum": 0, + "description": "Plays whose audience was estimated on this tier." + }, + "impressions": { + "type": "integer", + "minimum": 0, + "description": "Impressions those plays produced: their plays × their audience multiplier." + }, + "audience_multiplier": { + "type": "number", + "minimum": 0, + "description": "Effective `impressions / plays` of these plays, declared rather than inferred. Optional on `currency_measured` entries when the currency's terms prohibit disclosing it." + }, + "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 b0712e9d91e..85859305c5e 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 whose currency terms prohibit disclosing it." + } }, "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..0ee65d81fd6 --- /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. 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 seller-operated sensors, 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 2cbdd942874..c5bcf8b76ec 100644 --- a/static/schemas/source/index.json +++ b/static/schemas/source/index.json @@ -1606,6 +1606,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..974b467a630 --- /dev/null +++ b/tests/dooh-impression-basis.test.cjs @@ -0,0 +1,203 @@ +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 and the counts it relates agree to within half a percent. +function assertMultiplier(multiplier, impressions, plays, where) { + assert.ok(plays > 0, `${where}: plays`); + const ratio = impressions / plays; + assert.ok(Math.abs(ratio - multiplier) / ratio < 0.005, `${where}: ${impressions} / ${plays} = ${ratio}, declared ${multiplier}`); +} + +// Breakdown entries: one per tier, summing to the row's counts, each multiplier consistent. +function assertBreakdown(entries, plays, impressions, where) { + const tiers = entries.map((entry) => entry.impression_basis); + 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}`); +} + +// Every delivery row: either a single tier or a breakdown, a consistent multiplier, 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); + 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 nodes = [ + dooh.properties.impression_basis, dooh.properties.audience_multiplier, dooh.properties.basis_metric, + dooh.properties.impression_basis_breakdown, venue.impression_basis, venue.audience_multiplier, + point.impression_basis, point.audience_multiplier, point.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("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, validateForecast, 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"); + validateForecast = await compile("/schemas/core/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)); + const tiers = product.placements.map((placement) => placement.dooh_placement_attributes.impression_basis); + assert.deepEqual(tiers, ["sensor_measured", "seller_modeled"]); + }); + + it("forecast: the planning multiplier and the expected split reconcile with the midpoints", () => { + const forecast = fixture("forecast.json"); + assert.equal(validateForecast(forecast), true, JSON.stringify(validateForecast.errors, null, 2)); + for (const point of forecast.points) { + const plays = point.metrics.plays.mid; + const impressions = point.metrics.impressions.mid; + assertMultiplier(point.audience_multiplier, impressions, plays, point.label); + assertBreakdown(point.impression_basis_breakdown, plays, impressions, 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"); + for (const pkg of buy.by_package) { + assertDeliveryRow(pkg, pkg.package_id); + for (const placement of pkg.by_placement) + assertDeliveryRow(placement, placement.placement_id); + for (const key of ["plays", "impressions"]) + assert.equal(pkg.by_placement.reduce((sum, placement) => sum + placement[key], 0), pkg[key], `${pkg.package_id}: placements' ${key}`); + } + } + 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]; + const reject = (mutate) => { + const delivery = fixture("delivery.json"); + mutate(delivery.media_buy_deliveries[0].by_package[0].by_placement[0].dooh_metrics); + return validateDelivery(delivery); + }; + + it("an unknown tier", () => { + assert.equal(reject((dooh) => { dooh.impression_basis_breakdown[0].impression_basis = "panel_measured"; }), false); + }); + + it("a negative multiplier", () => { + assert.equal(reject((dooh) => { dooh.audience_multiplier = -1; }), false); + }); + + it("a breakdown entry without its tier", () => { + assert.equal(reject((dooh) => { delete dooh.impression_basis_breakdown[1].impression_basis; }), false); + }); + + it("an empty breakdown", () => { + assert.equal(reject((dooh) => { dooh.impression_basis_breakdown = []; }), false); + }); + + it("a basis_metric without its metric_id", () => { + assert.equal(reject((dooh) => { delete dooh.basis_metric.metric_id; }), false); + }); + + it("a breakdown entry without its counts", () => { + const entry = clone(placementRow().dooh_metrics.impression_basis_breakdown[0]); + delete entry.plays; + assert.equal(validateEntry(entry), false); + }); + + it("an unknown planned tier on a placement", () => { + const product = fixture("discovery-product.json"); + product.placements[0].dooh_placement_attributes.impression_basis = "panel_modeled"; + assert.equal(validateProduct(product), false); + }); + }); +}); diff --git a/tests/fixtures/dooh-impression-basis/delivery.json b/tests/fixtures/dooh-impression-basis/delivery.json new file mode 100644 index 00000000000..5db0055e309 --- /dev/null +++ b/tests/fixtures/dooh-impression-basis/delivery.json @@ -0,0 +1,79 @@ +{ + "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, + "audience_multiplier": 15.68, + "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, + "audience_multiplier": 15.68, + "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, + "audience_multiplier": 18.35, + "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..ac3e1695f28 --- /dev/null +++ b/tests/fixtures/dooh-impression-basis/forecast.json @@ -0,0 +1,20 @@ +{ + "points": [{ + "label": "Available from 2026-11-09 to 2026-11-15", + "metrics": { + "plays": { "mid": 86100 }, + "impressions": { "mid": 1356600 }, + "spend": { "mid": 10852.8 } + }, + "audience_multiplier": 15.76, + "impression_basis_breakdown": [ + { "impression_basis": "sensor_measured", "plays": 27800, "impressions": 517080, "audience_multiplier": 18.6 }, + { "impression_basis": "seller_modeled", "plays": 58300, "impressions": 839520, "audience_multiplier": 14.4 } + ] + }], + "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 09ea5b159b7..ed470af2713 100644 --- a/tests/x-added-in-3-3-sweep.test.cjs +++ b/tests/x-added-in-3-3-sweep.test.cjs @@ -42,6 +42,9 @@ const WHOLE_FILE_3_3 = [ 'core/reporting-subscription-state.json', 'core/reporting-subscription-coverage.json', 'enums/reporting-dimension.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 = [ @@ -73,6 +76,20 @@ 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', 'audience_multiplier']], + ['core/forecast-point.json', ['properties', 'impression_basis']], + ['core/forecast-point.json', ['properties', 'audience_multiplier']], + ['core/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']], From cc6f42df8f8284e3f59551fb65f427aea680db73 Mon Sep 17 00:00:00 2001 From: Aymeric Le Corre Date: Mon, 9 Nov 2026 15:56:26 +0100 Subject: [PATCH 2/5] feat(schema): apply the WG brief to the DOOH impression basis (RFC #7253) - A breakdown has at least two entries (minItems 2), with distinct tiers (prose and test: draft-07 cannot count them), and never sits beside a row-level impression_basis (dependencies on dooh_metrics and on forecast points). - A row with a breakdown SHOULD omit its blended audience_multiplier; the delivery fixture drops it from totals, the package and the concourse row. - A forecast breakdown SHOULD include the fallback the seller expects; the forecast fixture puts 30% of the concourse plays on seller_modeled. - dooh.mdx and the schema descriptions state the seller MUSTs for rows mixing tiers and what buyers must not misread: tiers are different units, billing is unchanged, a blended multiplier misleads, a filter on impression_basis misses mixed rows. - Tests: parent tier entries sum their children's; negative vectors for a single-entry breakdown, a repeated tier and a row carrying both fields. --- .changeset/dooh-impression-basis.md | 2 +- docs/creative/channels/dooh.mdx | 30 ++++++-- docs/reference/experimental-status.mdx | 2 +- .../schemas/source/core/delivery-metrics.json | 17 +++-- .../schemas/source/core/forecast-point.json | 13 +++- .../impression-basis-breakdown-entry.json | 2 +- .../enums/impression-estimation-basis.json | 2 +- tests/dooh-impression-basis.test.cjs | 73 ++++++++++++++++--- .../dooh-impression-basis/delivery.json | 3 - .../dooh-impression-basis/forecast.json | 9 +-- 10 files changed, 117 insertions(+), 36 deletions(-) diff --git a/.changeset/dooh-impression-basis.md b/.changeset/dooh-impression-basis.md index 20cac47b261..c38dceb8611 100644 --- a/.changeset/dooh-impression-basis.md +++ b/.changeset/dooh-impression-basis.md @@ -2,4 +2,4 @@ "adcontextprotocol": minor --- -Add the experimental DOOH impression basis (feature id `media_buy.dooh_impression_basis`, RFC #7253): a shared `enums/impression-estimation-basis.json` tier enum (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`) that says what kind of number a DOOH `impressions` figure (`plays × audience multiplier`) is. Delivery rows carry `dooh_metrics.impression_basis`, the declared `audience_multiplier`, a `basis_metric` pointer to the `vendor_metric_values[]` row a sensor audience comes from, and, for a row whose plays were estimated on different tiers, an `impression_basis_breakdown[]` (`core/impression-basis-breakdown-entry.json`) whose entries sum to the row's plays and impressions; `venue_breakdown[]` rows may carry the tier and multiplier. Forecast points carry the same declaration and the planning multiplier outside `metrics`, and product and canonical `dooh_placement_attributes` the planned tier and multiplier. `hybrid` is a seller model calibrated by the seller's own sensors, never a published currency nor a mix of tiers. All fields are optional; `ooh_metrics.estimation_basis` and the closed canonical forecast schemas are unchanged. +Add the experimental DOOH impression basis (feature id `media_buy.dooh_impression_basis`, RFC #7253): a shared `enums/impression-estimation-basis.json` tier enum (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`) that says what kind of number a DOOH `impressions` figure (`plays × audience multiplier`) is. Delivery rows carry `dooh_metrics.impression_basis`, the declared `audience_multiplier`, a `basis_metric` pointer to the `vendor_metric_values[]` row a sensor audience comes from, and, for a row whose plays were estimated on different tiers, an `impression_basis_breakdown[]` (`core/impression-basis-breakdown-entry.json`) of at least two entries with distinct tiers, which sum exactly to the row's plays and impressions and replace the row-level tier (a row never carries both) and the blended multiplier; `venue_breakdown[]` rows may carry the tier and multiplier. Forecast points carry the same declaration and the planning multiplier outside `metrics`, a forecast breakdown including the fallback the seller expects, and product and canonical `dooh_placement_attributes` the planned tier and multiplier. `hybrid` is a seller model calibrated by the seller's own sensors, never a published currency nor a mix of tiers. All fields are optional; `ooh_metrics.estimation_basis` and the closed canonical forecast schemas are unchanged. diff --git a/docs/creative/channels/dooh.mdx b/docs/creative/channels/dooh.mdx index 90cdb60755d..3fc11ef570f 100644 --- a/docs/creative/channels/dooh.mdx +++ b/docs/creative/channels/dooh.mdx @@ -260,11 +260,32 @@ Proof-of-play reporting uses `plays` for the raw playout count and `impressions` 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`: -- **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. -- **Forecast.** A forecast point carries the planning `audience_multiplier`, so `metrics.impressions.mid ≈ metrics.plays.mid × audience_multiplier`, and either the point's single `impression_basis` or an `impression_basis_breakdown` of the expected plays per tier. -- **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, one entry per tier summing to the row's `plays` and `impressions`. 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. +- **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`, so `metrics.impressions.mid ≈ metrics.plays.mid × 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. +- **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. -`hybrid` is a seller model calibrated by the seller's own sensors, never a published currency figure and never a mix of plays on different tiers, which the breakdown reports. A placement row of a product mixing both tiers: +`hybrid` is a seller model calibrated by the seller's own sensors, 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. +- **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. + +A placement row whose sensor-equipped screens fell back to the seller's model for part of the flight: ```json { @@ -274,7 +295,6 @@ A DOOH `impressions` figure is `plays × audience multiplier`, and the multiplie "plays": 27805, "dooh_metrics": { "screens_used": 85, - "audience_multiplier": 18.35, "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 } diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index 37a623a438f..17552d7d819 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -152,7 +152,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` / `audience_multiplier` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/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`), with one production adopter so far, whose network mixes sensor-measured and seller-modeled screens. The boundary of `hybrid` (a seller model calibrated by the seller's sensors, never a published currency and never a mix of plays on different tiers), the breakdown that reports such a mix, whether the multiplier is disclosed on `currency_measured` rows, and whether `impression_basis` becomes required for the `sales-dooh` claim are open for the working group. `ooh_metrics.estimation_basis` keeps its inline two-value enum. The closed canonical forecast schemas do not carry these fields in 3.x (DR-0036). | +| `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` / `audience_multiplier` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/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`), with one production adopter so far, whose network mixes sensor-measured and seller-modeled screens. Per the working group's decision brief on #7253: `hybrid` is a seller model calibrated by the seller's sensors, never a published currency and never a mix of plays on different tiers; a row mixing tiers reports a breakdown of at least two distinct tiers and never a row-level tier beside it; the multiplier is SHOULD on `sensor_measured` and `hybrid` rows and optional on `currency_measured` ones; and `impression_basis` becomes required for the `sales-dooh` claim in 4.0, the shape holding until then. `ooh_metrics.estimation_basis` keeps its inline two-value enum. The closed canonical forecast schemas do not carry these fields before 4.0 (DR-0036). | | `media_buy.audience_evidence_targets` | The `target_audiences[]` field, a sibling of `audience_evidence_requirements` on `core/product-filters.json` (`get_products` `filters`) and `media-buy/package-request.json` (`create_media_buy` packages), and its item schema `core/audience-evidence-target.json` (`audience`, `relationship`, `minimum_value`) ([RFC #8125](https://github.com/adcontextprotocol/adcp/issues/8125)). See [audience evidence requirements](/docs/media-buy/task-reference/get_products#audience-evidence-requirements). | Structured soft and hard audience preference over `audience_evidence`, with a single adopter so far and no field-testing across parties yet. The exact-match audience rule (no superset, subset, or adjusted-share matching), AND across targets, the lack of a baseline on `index` targets, the `minimum_value` units, the `maxItems` bound, and whether per-target satisfaction is reported in `audience_evidence_selections` may change. The field is a sibling rather than a member of the closed `audience_evidence_requirements` schemas, because a minor release never changes a closed schema. The closed `buy_products` purchase schemas and the closed `list_products` `offer_filters` do not carry it in 3.3; it arrives there in 4.0 (see the [4.0 compatibility check](/docs/reference/migration/v4-compatibility#purchase_target_audiences_required_in_4_0)), together with the purchase-snapshot echo. The `enums/audience-evidence-relationship.json` file carries the same values as the stable 3.2 `audience_evidence.relationship` enum, which stays inline and unchanged. Sellers that evaluate `target_audiences` declare the id; a seller that does not declare it MUST fail a `required` request with `UNSUPPORTED_FEATURE` rather than ignore it. | | `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/static/schemas/source/core/delivery-metrics.json b/static/schemas/source/core/delivery-metrics.json index 4a1cc842a58..80db0c0530a 100644 --- a/static/schemas/source/core/delivery-metrics.json +++ b/static/schemas/source/core/delivery-metrics.json @@ -282,14 +282,14 @@ "$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 aggregates plays estimated on different tiers, omit it and report `impression_basis_breakdown`. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + "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 effective `impressions / plays`, declared rather than inferred, so a verifier can check `impressions ≈ plays × audience_multiplier` and a buyer can compare rows. 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, for currencies whose terms prohibit disclosing it." + "description": "Experimental (media_buy.dooh_impression_basis). The row's effective `impressions / plays`, declared rather than inferred, so a verifier can check `impressions ≈ plays × audience_multiplier` and a buyer can compare rows. 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, for currencies whose terms prohibit disclosing it. 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", @@ -317,11 +317,11 @@ "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 screen that fell back to the seller's model while its sensor was not reporting — one entry per tier, whose `plays` and `impressions` sum to the row's. A row reports either `impression_basis` or this breakdown. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`.", + "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 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": 1 + "minItems": 2 }, "venue_breakdown": { "type": "array", @@ -360,14 +360,14 @@ "$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." + "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." }, "audience_multiplier": { "type": "number", "minimum": 0, "x-status": "experimental", "x-added-in": "3.3.0", - "description": "Experimental (media_buy.dooh_impression_basis). This venue's effective `impressions / loop_plays`, declared rather than inferred." + "description": "Experimental (media_buy.dooh_impression_basis). This venue's effective `impressions / loop_plays`, declared rather than inferred. SHOULD be omitted on a venue whose plays were estimated on different tiers." } }, "required": [ @@ -378,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 483c0788497..1f3d013633f 100644 --- a/static/schemas/source/core/forecast-point.json +++ b/static/schemas/source/core/forecast-point.json @@ -33,24 +33,24 @@ "$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, omit it and report `impression_basis_breakdown`. Lets forecast and delivery reconcile on the same declaration. Sellers that emit it MUST list `media_buy.dooh_impression_basis` in `experimental_features`." + "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 DOOH point: the `impressions / plays` the forecast applies, so `metrics.impressions.mid ≈ metrics.plays.mid × audience_multiplier`. A declaration, not a forecastable metric, so it sits outside `metrics`." + "description": "Experimental (media_buy.dooh_impression_basis). The planning multiplier of a single-tier DOOH point: the `impressions / plays` the forecast applies, so `metrics.impressions.mid ≈ metrics.plays.mid × audience_multiplier`. 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. A point reports either `impression_basis` or this breakdown.", + "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`. 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 plays and spend across tiers.", "items": { "$ref": "/schemas/core/impression-basis-breakdown-entry.json" }, - "minItems": 1 + "minItems": 2 }, "metrics": { "type": "object", @@ -148,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 index 440bf0425f5..42e3b64c8c7 100644 --- a/static/schemas/source/core/impression-basis-breakdown-entry.json +++ b/static/schemas/source/core/impression-basis-breakdown-entry.json @@ -4,7 +4,7 @@ "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 most one entry per tier. In a delivery row the entries' `plays` and `impressions` sum to the row's `plays` and `impressions`; in a forecast point they are the expected values behind the point's midpoints.", + "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": { diff --git a/static/schemas/source/enums/impression-estimation-basis.json b/static/schemas/source/enums/impression-estimation-basis.json index 0ee65d81fd6..40f48751121 100644 --- a/static/schemas/source/enums/impression-estimation-basis.json +++ b/static/schemas/source/enums/impression-estimation-basis.json @@ -2,7 +2,7 @@ "$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. 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`.", + "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 plays and spend across tiers. 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", diff --git a/tests/dooh-impression-basis.test.cjs b/tests/dooh-impression-basis.test.cjs index 974b467a630..545248d5909 100644 --- a/tests/dooh-impression-basis.test.cjs +++ b/tests/dooh-impression-basis.test.cjs @@ -30,9 +30,11 @@ function assertMultiplier(multiplier, impressions, plays, where) { assert.ok(Math.abs(ratio - multiplier) / ratio < 0.005, `${where}: ${impressions} / ${plays} = ${ratio}, declared ${multiplier}`); } -// Breakdown entries: one per tier, summing to the row's counts, each multiplier consistent. +// 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`); @@ -41,16 +43,36 @@ function assertBreakdown(entries, plays, impressions, where) { assertMultiplier(entry.audience_multiplier, entry.impressions, entry.plays, `${where} ${entry.impression_basis}`); } -// Every delivery row: either a single tier or a breakdown, a consistent multiplier, and a -// basis_metric that joins a vendor_metric_values row of the same object. +// 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) + 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); @@ -105,6 +127,16 @@ describe("DOOH impression basis schemas", () => { 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 exclusion = { impression_basis_breakdown: { not: { required: ["impression_basis"] } } }; + for (const schema of [dooh, point]) { + 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); @@ -132,15 +164,20 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s assert.deepEqual(tiers, ["sensor_measured", "seller_modeled"]); }); - it("forecast: the planning multiplier and the expected split reconcile with the midpoints", () => { + // 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)); for (const point of forecast.points) { const plays = point.metrics.plays.mid; const impressions = point.metrics.impressions.mid; - assertMultiplier(point.audience_multiplier, impressions, plays, point.label); 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("delivery: totals, package and placements carry a consistent basis, including a sensor screen that fell back", () => { @@ -148,12 +185,12 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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); - for (const key of ["plays", "impressions"]) - assert.equal(pkg.by_placement.reduce((sum, placement) => sum + placement[key], 0), pkg[key], `${pkg.package_id}: placements' ${key}`); + 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; @@ -180,8 +217,26 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s assert.equal(reject((dooh) => { delete dooh.impression_basis_breakdown[1].impression_basis; }), false); }); - it("an empty breakdown", () => { + it("a breakdown with fewer than two entries", () => { + assert.equal(reject((dooh) => { dooh.impression_basis_breakdown = [dooh.impression_basis_breakdown[0]]; }), false); assert.equal(reject((dooh) => { dooh.impression_basis_breakdown = []; }), false); + const point = fixture("forecast.json"); + point.points[0].impression_basis_breakdown.pop(); + assert.equal(validateForecast(point), false); + }); + + 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", () => { + assert.equal(reject((dooh) => { dooh.impression_basis = "sensor_measured"; }), false); + const forecast = fixture("forecast.json"); + forecast.points[0].impression_basis = "seller_modeled"; + assert.equal(validateForecast(forecast), false); }); it("a basis_metric without its metric_id", () => { diff --git a/tests/fixtures/dooh-impression-basis/delivery.json b/tests/fixtures/dooh-impression-basis/delivery.json index 5db0055e309..ae72a47181e 100644 --- a/tests/fixtures/dooh-impression-basis/delivery.json +++ b/tests/fixtures/dooh-impression-basis/delivery.json @@ -14,7 +14,6 @@ "plays": 86072, "dooh_metrics": { "screens_used": 256, - "audience_multiplier": 15.68, "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 } @@ -31,7 +30,6 @@ "plays": 86072, "dooh_metrics": { "screens_used": 256, - "audience_multiplier": 15.68, "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 } @@ -45,7 +43,6 @@ "plays": 27805, "dooh_metrics": { "screens_used": 85, - "audience_multiplier": 18.35, "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 } diff --git a/tests/fixtures/dooh-impression-basis/forecast.json b/tests/fixtures/dooh-impression-basis/forecast.json index ac3e1695f28..a23fe58b18c 100644 --- a/tests/fixtures/dooh-impression-basis/forecast.json +++ b/tests/fixtures/dooh-impression-basis/forecast.json @@ -3,13 +3,12 @@ "label": "Available from 2026-11-09 to 2026-11-15", "metrics": { "plays": { "mid": 86100 }, - "impressions": { "mid": 1356600 }, - "spend": { "mid": 10852.8 } + "impressions": { "mid": 1346592 }, + "spend": { "mid": 10772.74 } }, - "audience_multiplier": 15.76, "impression_basis_breakdown": [ - { "impression_basis": "sensor_measured", "plays": 27800, "impressions": 517080, "audience_multiplier": 18.6 }, - { "impression_basis": "seller_modeled", "plays": 58300, "impressions": 839520, "audience_multiplier": 14.4 } + { "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", From 04ec16431cf21571a5bc14bd2b0bff31a113968a Mon Sep 17 00:00:00 2001 From: Aymeric Le Corre Date: Wed, 11 Nov 2026 21:30:25 +0100 Subject: [PATCH 3/5] docs(dooh): release docs and review fixes for the impression basis (RFC #7253) - Release docs: a bullet and the feature id in whats-new-in-3-3, the Channels bullet and a row in the experimental-surfaces table of release-notes, a bullet in the 3.2 to 3.3 migration guide. - No more "closed" canonical forecast schemas in the changeset and the experimental-status row; the changeset is shorter. - index.json lists core/impression-basis-breakdown-entry.json. - Each negative vector asserts the keyword it fails on. --- .changeset/dooh-impression-basis.md | 8 ++++++- docs/reference/experimental-status.mdx | 2 +- docs/reference/migration/3-2-to-3-3.mdx | 1 + docs/reference/release-notes.mdx | 3 ++- docs/reference/whats-new-in-3-3.mdx | 3 ++- static/schemas/source/index.json | 4 ++++ tests/dooh-impression-basis.test.cjs | 28 ++++++++++++++----------- 7 files changed, 33 insertions(+), 16 deletions(-) diff --git a/.changeset/dooh-impression-basis.md b/.changeset/dooh-impression-basis.md index c38dceb8611..78b029697f4 100644 --- a/.changeset/dooh-impression-basis.md +++ b/.changeset/dooh-impression-basis.md @@ -2,4 +2,10 @@ "adcontextprotocol": minor --- -Add the experimental DOOH impression basis (feature id `media_buy.dooh_impression_basis`, RFC #7253): a shared `enums/impression-estimation-basis.json` tier enum (`currency_measured`, `seller_modeled`, `sensor_measured`, `hybrid`) that says what kind of number a DOOH `impressions` figure (`plays × audience multiplier`) is. Delivery rows carry `dooh_metrics.impression_basis`, the declared `audience_multiplier`, a `basis_metric` pointer to the `vendor_metric_values[]` row a sensor audience comes from, and, for a row whose plays were estimated on different tiers, an `impression_basis_breakdown[]` (`core/impression-basis-breakdown-entry.json`) of at least two entries with distinct tiers, which sum exactly to the row's plays and impressions and replace the row-level tier (a row never carries both) and the blended multiplier; `venue_breakdown[]` rows may carry the tier and multiplier. Forecast points carry the same declaration and the planning multiplier outside `metrics`, a forecast breakdown including the fallback the seller expects, and product and canonical `dooh_placement_attributes` the planned tier and multiplier. `hybrid` is a seller model calibrated by the seller's own sensors, never a published currency nor a mix of tiers. All fields are optional; `ooh_metrics.estimation_basis` and the closed canonical forecast schemas are unchanged. +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 multiplier. +- Forecast: forecast points carry the same fields, outside `metrics`. A breakdown includes the fallback the seller expects. +- Discovery: `dooh_placement_attributes` carries the planned tier and multiplier. + +`hybrid` is a seller model calibrated by the seller's own sensors, never a published currency nor a mix of tiers. All fields are optional. `ooh_metrics.estimation_basis` and the canonical forecast schemas are unchanged. diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index 17552d7d819..36c3e6f2262 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -152,7 +152,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` / `audience_multiplier` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/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`), with one production adopter so far, whose network mixes sensor-measured and seller-modeled screens. Per the working group's decision brief on #7253: `hybrid` is a seller model calibrated by the seller's sensors, never a published currency and never a mix of plays on different tiers; a row mixing tiers reports a breakdown of at least two distinct tiers and never a row-level tier beside it; the multiplier is SHOULD on `sensor_measured` and `hybrid` rows and optional on `currency_measured` ones; and `impression_basis` becomes required for the `sales-dooh` claim in 4.0, the shape holding until then. `ooh_metrics.estimation_basis` keeps its inline two-value enum. The closed canonical forecast schemas do not carry these fields before 4.0 (DR-0036). | +| `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` / `audience_multiplier` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/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 the seller's own sensors, 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. The canonical forecast schemas (`list_products` and the proposal tasks) do not carry these fields yet. | | `media_buy.audience_evidence_targets` | The `target_audiences[]` field, a sibling of `audience_evidence_requirements` on `core/product-filters.json` (`get_products` `filters`) and `media-buy/package-request.json` (`create_media_buy` packages), and its item schema `core/audience-evidence-target.json` (`audience`, `relationship`, `minimum_value`) ([RFC #8125](https://github.com/adcontextprotocol/adcp/issues/8125)). See [audience evidence requirements](/docs/media-buy/task-reference/get_products#audience-evidence-requirements). | Structured soft and hard audience preference over `audience_evidence`, with a single adopter so far and no field-testing across parties yet. The exact-match audience rule (no superset, subset, or adjusted-share matching), AND across targets, the lack of a baseline on `index` targets, the `minimum_value` units, the `maxItems` bound, and whether per-target satisfaction is reported in `audience_evidence_selections` may change. The field is a sibling rather than a member of the closed `audience_evidence_requirements` schemas, because a minor release never changes a closed schema. The closed `buy_products` purchase schemas and the closed `list_products` `offer_filters` do not carry it in 3.3; it arrives there in 4.0 (see the [4.0 compatibility check](/docs/reference/migration/v4-compatibility#purchase_target_audiences_required_in_4_0)), together with the purchase-snapshot echo. The `enums/audience-evidence-relationship.json` file carries the same values as the stable 3.2 `audience_evidence.relationship` enum, which stays inline and unchanged. Sellers that evaluate `target_audiences` declare the id; a seller that does not declare it MUST fail a `required` request with `UNSUPPORTED_FEATURE` rather than ignore it. | | `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 d8b0b9984be..d6de7405383 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -732,6 +732,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`) has two uses, both on open schemas: `measurement_terms.billing_measurement.counting_mechanisms[]` declares what the billing count is counted from (a seller whose own system is the named vendor SHOULD declare it; absence means undeclared), and `vendor_metric_provenance[]` on delivery metrics 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 both fields. - **Audience evidence targets and invoice lines.** `target_audiences[]` (`media_buy.audience_evidence_targets`, [#8215](https://github.com/adcontextprotocol/adcp/pull/8215)) names the audience a buyer wants evidence for beside `audience_evidence_requirements`, satisfied only by an admissible evidence item for exactly that audience; it is never a targeting predicate. `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 d3e18dc711a..1d09973a7b2 100644 --- a/docs/reference/release-notes.mdx +++ b/docs/reference/release-notes.mdx @@ -35,7 +35,7 @@ Each beta is immutable. The `3.3-beta` documentation selector advances to the la - **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` (#8038); `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. @@ -134,6 +134,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 60c66a14479..317848386fe 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -125,6 +125,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). @@ -255,7 +256,7 @@ Three changes need no new rule. Schema validation now refuses a `period_duration ## Experimental in 3.3 -New feature ids are `media_buy.spot_lifecycle`, `media_buy.daypart_granularity`, `creative.broadcast_loudness`, `media_buy.hold_policy`, `media_buy.hold_ranking`, `media_buy.installment_holds`, `media_buy.hold_extension`, `media_buy.delegated_composition`, `media_buy.collection_cards`, `media_buy.collection_catalog`, `brand.collection_links`, `media_buy.open_opportunities`, `media_buy.lineage`, `media_buy.delivery_projection`, `media_buy.installment_lifecycle`, `media_buy.collection_lists`, `media_buy.offline_delivery_metrics`, `signals.signal_lifecycle`, `signing.web_bot_auth`, `account.agent_onboarding`, `account.requests`, `media_buy.reporting_subscriptions`, `creative.live_updates`, `media_buy.seller_offers`, `media_buy.price_adjustments`, `media_buy.execution_readiness`, `media_buy.gender_targeting`, `media_buy.measurement_provenance`, `media_buy.audience_evidence_targets`, `account.invoice_lines`, `signals.pricing_groups`, `signals.delivery_methods`, `security.profiles`, and `identity.trust_json`. `media_buy.purchase_rights` and `media_buy.installment_selection` shipped in beta.1 and are withdrawn, so they are not registered. `media_buy.offline_delivery_metrics` registers the new `print_metrics` block together with the 3.2 `ooh_metrics` block. `identity.trust_json` publishes the `trust.json` v1 schemas, identifying agents by origin with no keys in the record; the Web Bot Auth profile reads it, and publishers declare nothing ([trust.json](/docs/reference/trust-json)). Governance budget periods extend the existing `governance.campaign` cluster, `get_principal` relationship status extends `protocol.principal`, and rights channel restrictions extend `brand.rights_lifecycle`. The `creative.evaluator` surface on `build_creative` drops its account-arranged `evaluator_id` source form and withdraws the `list_evaluators` follow-on: sources are now inline `exemplars` or an allowlisted `agent_url`, and a seller's house evaluator is an agent it lists in `creative_policy.accepted_verifiers[]` ([migration](/docs/reference/migration/3-2-to-3-3#experimental-creative-evaluator-drops-evaluator_id)). Reliable Reporting carries a new breaking-change notice: older superseded snapshots [may be compacted](/docs/reference/migration/3-2-to-3-3#superseded-reporting-snapshots-may-be-compacted) no earlier than the first minor after November 20, 2026. The per-surface status table is in the [release notes](/docs/reference/release-notes#experimental-surfaces-in-3-3). +New feature ids are `media_buy.spot_lifecycle`, `media_buy.daypart_granularity`, `creative.broadcast_loudness`, `media_buy.hold_policy`, `media_buy.hold_ranking`, `media_buy.installment_holds`, `media_buy.hold_extension`, `media_buy.delegated_composition`, `media_buy.collection_cards`, `media_buy.collection_catalog`, `brand.collection_links`, `media_buy.open_opportunities`, `media_buy.lineage`, `media_buy.delivery_projection`, `media_buy.installment_lifecycle`, `media_buy.collection_lists`, `media_buy.offline_delivery_metrics`, `media_buy.dooh_impression_basis`, `signals.signal_lifecycle`, `signing.web_bot_auth`, `account.agent_onboarding`, `account.requests`, `media_buy.reporting_subscriptions`, `creative.live_updates`, `media_buy.seller_offers`, `media_buy.price_adjustments`, `media_buy.execution_readiness`, `media_buy.gender_targeting`, `media_buy.measurement_provenance`, `media_buy.audience_evidence_targets`, `account.invoice_lines`, `signals.pricing_groups`, `signals.delivery_methods`, `security.profiles`, and `identity.trust_json`. `media_buy.purchase_rights` and `media_buy.installment_selection` shipped in beta.1 and are withdrawn, so they are not registered. `media_buy.offline_delivery_metrics` registers the new `print_metrics` block together with the 3.2 `ooh_metrics` block. `identity.trust_json` publishes the `trust.json` v1 schemas, identifying agents by origin with no keys in the record; the Web Bot Auth profile reads it, and publishers declare nothing ([trust.json](/docs/reference/trust-json)). Governance budget periods extend the existing `governance.campaign` cluster, `get_principal` relationship status extends `protocol.principal`, and rights channel restrictions extend `brand.rights_lifecycle`. The `creative.evaluator` surface on `build_creative` drops its account-arranged `evaluator_id` source form and withdraws the `list_evaluators` follow-on: sources are now inline `exemplars` or an allowlisted `agent_url`, and a seller's house evaluator is an agent it lists in `creative_policy.accepted_verifiers[]` ([migration](/docs/reference/migration/3-2-to-3-3#experimental-creative-evaluator-drops-evaluator_id)). Reliable Reporting carries a new breaking-change notice: older superseded snapshots [may be compacted](/docs/reference/migration/3-2-to-3-3#superseded-reporting-snapshots-may-be-compacted) no earlier than the first minor after November 20, 2026. The per-surface status table is in the [release notes](/docs/reference/release-notes#experimental-surfaces-in-3-3). 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. diff --git a/static/schemas/source/index.json b/static/schemas/source/index.json index 0d5ab51f6ac..dc403bcf954 100644 --- a/static/schemas/source/index.json +++ b/static/schemas/source/index.json @@ -333,6 +333,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" diff --git a/tests/dooh-impression-basis.test.cjs b/tests/dooh-impression-basis.test.cjs index 545248d5909..30e744ea366 100644 --- a/tests/dooh-impression-basis.test.cjs +++ b/tests/dooh-impression-basis.test.cjs @@ -199,30 +199,34 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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 validateDelivery(delivery); + return failures(validateDelivery, delivery); }; it("an unknown tier", () => { - assert.equal(reject((dooh) => { dooh.impression_basis_breakdown[0].impression_basis = "panel_measured"; }), false); + assertFailsOn(reject((dooh) => { dooh.impression_basis_breakdown[0].impression_basis = "panel_measured"; }), "enum"); }); it("a negative multiplier", () => { - assert.equal(reject((dooh) => { dooh.audience_multiplier = -1; }), false); + assertFailsOn(reject((dooh) => { dooh.audience_multiplier = -1; }), "minimum"); }); it("a breakdown entry without its tier", () => { - assert.equal(reject((dooh) => { delete dooh.impression_basis_breakdown[1].impression_basis; }), false); + assertFailsOn(reject((dooh) => { delete dooh.impression_basis_breakdown[1].impression_basis; }), "required"); }); it("a breakdown with fewer than two entries", () => { - assert.equal(reject((dooh) => { dooh.impression_basis_breakdown = [dooh.impression_basis_breakdown[0]]; }), false); - assert.equal(reject((dooh) => { dooh.impression_basis_breakdown = []; }), false); + 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(); - assert.equal(validateForecast(point), false); + assertFailsOn(failures(validateForecast, point), "minItems"); }); it("a breakdown repeating a tier", () => { @@ -233,26 +237,26 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s }); it("a row carrying both a tier and a breakdown", () => { - assert.equal(reject((dooh) => { dooh.impression_basis = "sensor_measured"; }), false); + assertFailsOn(reject((dooh) => { dooh.impression_basis = "sensor_measured"; }), "not"); const forecast = fixture("forecast.json"); forecast.points[0].impression_basis = "seller_modeled"; - assert.equal(validateForecast(forecast), false); + assertFailsOn(failures(validateForecast, forecast), "not"); }); it("a basis_metric without its metric_id", () => { - assert.equal(reject((dooh) => { delete dooh.basis_metric.metric_id; }), false); + 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; - assert.equal(validateEntry(entry), false); + 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"; - assert.equal(validateProduct(product), false); + assertFailsOn(failures(validateProduct, product), "enum"); }); }); }); From 546cf8bbe0821a0374d7ad1a260429acfaaff50b Mon Sep 17 00:00:00 2001 From: Aymeric Le Corre Date: Mon, 16 Nov 2026 10:09:23 +0100 Subject: [PATCH 4/5] feat(schema): canonical forecast fields and review fixes for the impression basis (RFC #7253) - The three forecast fields and the exclusion on canonical-forecast-point.json, so list_products and the proposal tasks carry them; the fixtures validate against the canonical product and forecast schemas too. - Breakdown plays and impressions are numbers, so fractional forecast mids can sum exactly; a point with a breakdown carries both mids. - impressions is authoritative; the multiplier is impressions / plays, rounded, and a receiver must not reject a rounding difference. - The venue multiplier is per play, on the row's basis, not per loop_plays. - Wording: where basis_metric's vendor_metric_values row sits, hybrid with sensors on the seller's screens whoever supplies them, sensor_measured compared within one basis_metric, OpenRTB qty.sourcetype, the changeset's forecast fields, the canonical placement descriptions. --- .changeset/dooh-impression-basis.md | 4 +- docs/creative/channels/dooh.mdx | 9 +++-- docs/reference/experimental-status.mdx | 2 +- .../source/core/canonical-forecast-point.json | 26 ++++++++++++ .../source/core/canonical-placement.json | 4 +- .../schemas/source/core/delivery-metrics.json | 8 ++-- .../schemas/source/core/forecast-point.json | 4 +- .../impression-basis-breakdown-entry.json | 10 ++--- .../enums/impression-estimation-basis.json | 4 +- tests/dooh-impression-basis.test.cjs | 40 ++++++++++++++++--- tests/x-added-in-3-3-sweep.test.cjs | 3 ++ 11 files changed, 87 insertions(+), 27 deletions(-) diff --git a/.changeset/dooh-impression-basis.md b/.changeset/dooh-impression-basis.md index 78b029697f4..ac316549fde 100644 --- a/.changeset/dooh-impression-basis.md +++ b/.changeset/dooh-impression-basis.md @@ -5,7 +5,7 @@ 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 multiplier. -- Forecast: forecast points carry the same fields, outside `metrics`. A breakdown includes the fallback the seller expects. +- 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. -`hybrid` is a seller model calibrated by the seller's own sensors, never a published currency nor a mix of tiers. All fields are optional. `ooh_metrics.estimation_basis` and the canonical forecast schemas are unchanged. +`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 3fc11ef570f..c1d389030f1 100644 --- a/docs/creative/channels/dooh.mdx +++ b/docs/creative/channels/dooh.mdx @@ -258,13 +258,13 @@ 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`: +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`, so `metrics.impressions.mid ≈ metrics.plays.mid × 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. +- **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. -`hybrid` is a seller model calibrated by the seller's own sensors, never a published currency figure and never a mix of plays on different tiers, which the breakdown reports. +`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 @@ -280,10 +280,11 @@ A row never carries both `impression_basis` and a breakdown, and SHOULD omit its ### 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. +- **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: diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index f84893c2692..007d6e0f75f 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -154,7 +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` / `audience_multiplier` on `venue_breakdown[]` rows; the same declaration and planning multiplier on `core/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 the seller's own sensors, 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. The canonical forecast schemas (`list_products` and the proposal tasks) do not carry these fields yet. | +| `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` / `audience_multiplier` 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/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 163ccec82c5..750d65f73fb 100644 --- a/static/schemas/source/core/canonical-placement.json +++ b/static/schemas/source/core/canonical-placement.json @@ -75,14 +75,14 @@ "$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. Delivery reports the realised tiers." + "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." + "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 whose currency terms prohibit disclosing it." } }, "x-adcp-validation": { diff --git a/static/schemas/source/core/delivery-metrics.json b/static/schemas/source/core/delivery-metrics.json index 77821e7c935..2977fe3c4af 100644 --- a/static/schemas/source/core/delivery-metrics.json +++ b/static/schemas/source/core/delivery-metrics.json @@ -289,13 +289,13 @@ "minimum": 0, "x-status": "experimental", "x-added-in": "3.3.0", - "description": "Experimental (media_buy.dooh_impression_basis). The row's effective `impressions / plays`, declared rather than inferred, so a verifier can check `impressions ≈ plays × audience_multiplier` and a buyer can compare rows. 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, for currencies whose terms prohibit disclosing it. 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." + "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, for currencies whose terms prohibit disclosing it. 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 of the same object 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 `vendor_metric_values[]` row MUST be present in the same object.", + "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", @@ -317,7 +317,7 @@ "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 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`.", + "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" }, @@ -367,7 +367,7 @@ "minimum": 0, "x-status": "experimental", "x-added-in": "3.3.0", - "description": "Experimental (media_buy.dooh_impression_basis). This venue's effective `impressions / loop_plays`, declared rather than inferred. SHOULD be omitted on a venue whose plays were estimated on different tiers." + "description": "Experimental (media_buy.dooh_impression_basis). This venue's audience per play, on the same basis as the row's `audience_multiplier`: `impressions` divided by the plays, not by `loop_plays`. SHOULD be omitted on a venue whose plays were estimated on different tiers." } }, "required": [ diff --git a/static/schemas/source/core/forecast-point.json b/static/schemas/source/core/forecast-point.json index 1f3d013633f..a26b5bc764e 100644 --- a/static/schemas/source/core/forecast-point.json +++ b/static/schemas/source/core/forecast-point.json @@ -40,13 +40,13 @@ "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: the `impressions / plays` the forecast applies, so `metrics.impressions.mid ≈ metrics.plays.mid × audience_multiplier`. 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`." + "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`. 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 plays and spend across tiers.", + "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" }, diff --git a/static/schemas/source/core/impression-basis-breakdown-entry.json b/static/schemas/source/core/impression-basis-breakdown-entry.json index 42e3b64c8c7..04b2176a74f 100644 --- a/static/schemas/source/core/impression-basis-breakdown-entry.json +++ b/static/schemas/source/core/impression-basis-breakdown-entry.json @@ -12,19 +12,19 @@ "description": "Tier the audience of these plays was estimated on." }, "plays": { - "type": "integer", + "type": "number", "minimum": 0, - "description": "Plays whose audience was estimated on this tier." + "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": "integer", + "type": "number", "minimum": 0, - "description": "Impressions those plays produced: their plays × their audience multiplier." + "description": "Impressions those plays produced. Authoritative: `audience_multiplier` is derived from it, not the other way round." }, "audience_multiplier": { "type": "number", "minimum": 0, - "description": "Effective `impressions / plays` of these plays, declared rather than inferred. Optional on `currency_measured` entries when the currency's terms prohibit disclosing it." + "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 when the currency's terms prohibit disclosing it." }, "ext": { "$ref": "/schemas/core/ext.json" } }, diff --git a/static/schemas/source/enums/impression-estimation-basis.json b/static/schemas/source/enums/impression-estimation-basis.json index 40f48751121..dc03c27bf9e 100644 --- a/static/schemas/source/enums/impression-estimation-basis.json +++ b/static/schemas/source/enums/impression-estimation-basis.json @@ -2,7 +2,7 @@ "$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 plays and spend across tiers. 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`.", + "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", @@ -16,6 +16,6 @@ "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 seller-operated sensors, 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`." + "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/tests/dooh-impression-basis.test.cjs b/tests/dooh-impression-basis.test.cjs index 30e744ea366..6272e4a96a7 100644 --- a/tests/dooh-impression-basis.test.cjs +++ b/tests/dooh-impression-basis.test.cjs @@ -23,11 +23,13 @@ function fixture(name) { const clone = (value) => JSON.parse(JSON.stringify(value)); -// A declared multiplier and the counts it relates agree to within half a percent. +// 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; - assert.ok(Math.abs(ratio - multiplier) / ratio < 0.005, `${where}: ${impressions} / ${plays} = ${ratio}, declared ${multiplier}`); + 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 @@ -100,10 +102,12 @@ describe("DOOH impression basis schemas", () => { 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.audience_multiplier, 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"), ]; @@ -130,8 +134,9 @@ describe("DOOH impression basis schemas", () => { 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]) { + for (const schema of [dooh, point, canonicalPoint]) { assert.equal(schema.properties.impression_basis_breakdown.minItems, 2); assert.deepEqual(schema.dependencies, exclusion); } @@ -144,7 +149,7 @@ describe("DOOH impression basis schemas", () => { }); describe("DOOH impression basis fixtures: a product mixing sensor-measured and seller-modeled screens", () => { - let validateProduct, validateForecast, validateDelivery, validateEntry; + let validateProduct, validateCanonicalProduct, validateForecast, validateCanonicalForecast, validateDelivery, validateEntry; before(async () => { const ajv = new Ajv({ allErrors: true, strict: false, loadSchema: async (ref) => readSchema(ref) }); @@ -152,7 +157,9 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s // 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"); }); @@ -160,6 +167,8 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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"]); }); @@ -169,6 +178,8 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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; @@ -180,6 +191,20 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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)); @@ -214,7 +239,10 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s }); it("a negative multiplier", () => { - assertFailsOn(reject((dooh) => { dooh.audience_multiplier = -1; }), "minimum"); + // 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", () => { @@ -227,6 +255,7 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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", () => { @@ -241,6 +270,7 @@ describe("DOOH impression basis fixtures: a product mixing sensor-measured and s 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", () => { diff --git a/tests/x-added-in-3-3-sweep.test.cjs b/tests/x-added-in-3-3-sweep.test.cjs index 5fcc9d370dc..17b2b3222ae 100644 --- a/tests/x-added-in-3-3-sweep.test.cjs +++ b/tests/x-added-in-3-3-sweep.test.cjs @@ -88,6 +88,9 @@ const PROPERTIES_3_3 = [ ['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']], From 9ae366dff4f22429620fb8834f41531d54b745a9 Mon Sep 17 00:00:00 2001 From: "Constantine.mirin" Date: Mon, 16 Nov 2026 13:51:27 +0100 Subject: [PATCH 5/5] fix(schema): give DOOH venue rows plays instead of a multiplier Standards and reports carry the impression multiplier per play of one screen in one time slot (OpenRTB 2.6 `imp.qty.multiplier`, the UK and Geopath currencies); delivery reports give plays and impressions by venue, not a venue multiplier. Agreed with the adopter on the PR. - `venue_breakdown[]` rows carry `plays` instead of `audience_multiplier`. Each screen that played the spot counts one play, so synchronized screens count one play each. A venue's audience per play is `impressions / plays`. - The multiplier stays optional on `currency_measured` rows, entries and placements, without the reason about currency terms: no such currency is known, and `plays` and `impressions` reveal the ratio. Both venue fields are new in this release, so nothing shipped changes. --- .changeset/dooh-impression-basis.md | 2 +- docs/creative/channels/dooh.mdx | 2 +- docs/reference/experimental-status.mdx | 2 +- static/schemas/source/core/canonical-placement.json | 2 +- static/schemas/source/core/delivery-metrics.json | 6 +++--- .../source/core/impression-basis-breakdown-entry.json | 2 +- static/schemas/source/core/placement.json | 2 +- tests/dooh-impression-basis.test.cjs | 2 +- tests/x-added-in-3-3-sweep.test.cjs | 2 +- 9 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.changeset/dooh-impression-basis.md b/.changeset/dooh-impression-basis.md index ac316549fde..1f8b0a85764 100644 --- a/.changeset/dooh-impression-basis.md +++ b/.changeset/dooh-impression-basis.md @@ -4,7 +4,7 @@ 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 multiplier. +- 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. diff --git a/docs/creative/channels/dooh.mdx b/docs/creative/channels/dooh.mdx index c1d389030f1..bf996db6b13 100644 --- a/docs/creative/channels/dooh.mdx +++ b/docs/creative/channels/dooh.mdx @@ -262,7 +262,7 @@ A DOOH `impressions` figure is `plays × audience multiplier`, and the multiplie - **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. +- **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. diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index 7a87bff55ff..6448f2dda3b 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -154,7 +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` / `audience_multiplier` 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. | +| `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/static/schemas/source/core/canonical-placement.json b/static/schemas/source/core/canonical-placement.json index 750d65f73fb..8ec19643ba3 100644 --- a/static/schemas/source/core/canonical-placement.json +++ b/static/schemas/source/core/canonical-placement.json @@ -82,7 +82,7 @@ "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 whose currency terms prohibit disclosing it." + "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": { diff --git a/static/schemas/source/core/delivery-metrics.json b/static/schemas/source/core/delivery-metrics.json index 2977fe3c4af..98cee619cd9 100644 --- a/static/schemas/source/core/delivery-metrics.json +++ b/static/schemas/source/core/delivery-metrics.json @@ -289,7 +289,7 @@ "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, for currencies whose terms prohibit disclosing it. 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." + "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", @@ -362,12 +362,12 @@ "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." }, - "audience_multiplier": { + "plays": { "type": "number", "minimum": 0, "x-status": "experimental", "x-added-in": "3.3.0", - "description": "Experimental (media_buy.dooh_impression_basis). This venue's audience per play, on the same basis as the row's `audience_multiplier`: `impressions` divided by the plays, not by `loop_plays`. SHOULD be omitted on a venue whose plays were estimated on different tiers." + "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": [ diff --git a/static/schemas/source/core/impression-basis-breakdown-entry.json b/static/schemas/source/core/impression-basis-breakdown-entry.json index 04b2176a74f..d582c58bd0e 100644 --- a/static/schemas/source/core/impression-basis-breakdown-entry.json +++ b/static/schemas/source/core/impression-basis-breakdown-entry.json @@ -24,7 +24,7 @@ "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 when the currency's terms prohibit disclosing it." + "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" } }, diff --git a/static/schemas/source/core/placement.json b/static/schemas/source/core/placement.json index a6395c3e98c..607c9c35966 100644 --- a/static/schemas/source/core/placement.json +++ b/static/schemas/source/core/placement.json @@ -82,7 +82,7 @@ "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 whose currency terms prohibit disclosing it." + "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": { diff --git a/tests/dooh-impression-basis.test.cjs b/tests/dooh-impression-basis.test.cjs index 6272e4a96a7..55db5a5bac7 100644 --- a/tests/dooh-impression-basis.test.cjs +++ b/tests/dooh-impression-basis.test.cjs @@ -105,7 +105,7 @@ describe("DOOH impression basis schemas", () => { 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.audience_multiplier, + 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, diff --git a/tests/x-added-in-3-3-sweep.test.cjs b/tests/x-added-in-3-3-sweep.test.cjs index 17b2b3222ae..a9664d1ea12 100644 --- a/tests/x-added-in-3-3-sweep.test.cjs +++ b/tests/x-added-in-3-3-sweep.test.cjs @@ -84,7 +84,7 @@ const PROPERTIES_3_3 = [ ['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', 'audience_multiplier']], + ['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']],