Repository navigation
feat(schema): experimental DOOH impression basis (RFC #7253) - #8736
Conversation
…ol#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.
Preview approval requiredThis pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit |
IPR Policy Agreement Required@aymeric45 — thanks for the contribution. Before this PR can be merged, the AgenticAdvertising.Org IPR Policy requires your agreement. To agree, post a new comment on this PR with the exact phrase: Your signature is recorded once and covers all contributions to AAO repositories. See |
|
I have read the IPR Policy |
IPR Policy — signedThanks, @aymeric45. Your agreement to the IPR Policy is recorded at |
# Conflicts: # package.json # tests/x-added-in-3-3-sweep.test.cjs
…contextprotocol#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.
bokelley
left a comment
There was a problem hiding this comment.
@aymeric45, thank you, this is a careful implementation of the brief. Approving the design for the 3.3 RC (cut Mon Nov 16), provided items 1–3 below land by Thu Nov 12. Note that #8668 and #8792 merged to main today, so rebase onto current main as well.
Review of #8736 against the Nov 7 decision brief on #7253
Verdict: ready with nits. The schema, tests and dooh.mdx match the brief point by point. Before the RC, two text fixes and the release-doc bullets are needed. None of them changes the wire shape.
I checked head cc6f42d merged onto main df2446f, and that merge plus #8866 at fa7aefa.
Point by point
The five mixed-row MUSTs: all present. Each is stated in dooh.mdx ("Rows mixing tiers") and in the schema descriptions. Each is also enforced:
- Omit the row tier, and never use
hybridor the majority tier. Stated ondooh_metrics.impression_basisand on the forecast-pointimpression_basis. A row carrying both fails on the newdependenciesrule. - One entry per tier, with exact sums.
minItems: 2is in the schema. Distinct tiers and exact sums are checked by the test's invariant, because draft-07 cannot count entries per tier. - Fallback plays count as
seller_modeled. Stated in the breakdown description and the enum, and exercised by theconcourse_screensfixture row. - Each parent tier entry equals the sum of its children's entries. Stated, and checked across totals, the package and the placements.
- A venue that mixes tiers omits its tier. It is a MUST on
venue_breakdown[].impression_basis.
Decided items: all honoured.
- The feature id is
media_buy.dooh_impression_basis, and every new field is optional. - The basis is a tier, not a provider or an instrument.
- Option A wording is used for
currency_measuredandhybrid. - The multiplier is SHOULD on
sensor_measuredandhybrid, and optional oncurrency_measured. - Forecast fields sit outside
metrics. - An unknown tier is read as
seller_modeled. ooh_metrics.estimation_basisis untouched, and a test asserts it.- There is no new pricing model, and no
adagents.json, storyboard or filter changes. - Hardening is stated for 4.0, not 3.4.
- Discovery has no fallback field. Instead, a forecast breakdown SHOULD include the expected fallback, and the fixture puts 30% of concourse plays on fallback.
- A breakdown row or point SHOULD omit its blended multiplier, and the fixtures now do.
Negative vectors: all present, and each fails for the intended reason.
- A single-entry breakdown (delivery and forecast) fails on
minItems. - A row or point carrying both fields (delivery and forecast) fails on
not. - A repeated tier fails the test's invariant.
I re-ran the first four against Ajv and checked the failing keyword. The unmodified fixtures validate.
Experimental registration: complete.
- All 13 new properties carry
x-status: experimental. So do both new files. - Every top-level field names the feature id and the
experimental_featuresobligation. - The
experimental-status.mdxrow is present, and a test asserts it. - The new
dependenciessit on stable nodes:dooh_metricsand the forecast-point root. That is fine. They only bind the new experimental names, anddelivery-metrics.jsonalready uses the same pattern forooh_metrics.
x-added-in: complete. Every new property and both new files say 3.3.0, and both files are in the 3.3 sweep test's whole-file list. index.json lists the enum but not core/impression-basis-breakdown-entry.json. Other 3.3 item schemas are listed there, such as invoice-line, audience-evidence-target and match-key (nit below).
Release-doc bullets: missing. Every other 3.3 experimental feature id appears in the release docs, and this one appears in none of them:
- the feature-id list and a bullet in
whats-new-in-3-3.mdx; - the 3.3 summary and the experimental-surfaces table in
release-notes.mdx; - a bullet in
migration/3-2-to-3-3.mdx.
No test catches this, but the docs are archived at the release tag. Proposed text is below.
Interaction with #8866: no shared nodes, two textual conflicts.
- #8736 edits three things:
dooh_metrics, theforecast-point.jsonroot, and the two DOOH placement-attribute definitions. - #8866 opens or guards other nodes in the same files:
- the sibling DOOH screen-resolution, address and location definitions;
- the
canonical-placement.jsonroot, together with its newnot: {required: [format_ids]}guard; - two nodes in
delivery-metrics.jsonoutsidedooh_metrics.
- None of #8866's nodes is one #8736 edits.
- With both PRs merged:
- lint:
✓ additive-minor lint: source vs 3.2.10, 1017 files, 4 recorded non-additive changes, 0 new; - the DOOH suite passes 18/18;
- the additive-minor, canonical-forecast-parity and 3.3-sweep suites pass 90/90.
- lint:
- The conflicts are textual: the
test:schemasline inpackage.json, and the adjacentaudience_evidence_targetsrow inexperimental-status.mdx. Both resolve as unions. Whichever PR lands second rebases.
Requested before merge (Thu Nov 12)
1. Fix the closed-schema wording that #8866 makes false. #8866 opens canonical-forecast-point.json, canonical-delivery-forecast.json and dooh-inventory-summary.json, and the DR-0036 rule is being rewritten. Three places need to change:
- In the changeset, "the closed canonical forecast schemas are unchanged" → "the canonical forecast schemas are unchanged". The changeset text ships in
CHANGELOG.md. - In the
experimental-status.mdxrow, "The closed canonical forecast schemas do not carry these fields before 4.0 (DR-0036)." → "The canonical forecast schemas (list_productsand the proposal tasks) do not carry these fields yet." - In the PR description, under Follow-ups, the canonical-forecast and
dooh-inventory-summaryitems. Once #8866 lands, both schemas are open.
2. Add the release-doc bullets. Add them in this PR, or in the RC release-docs refresh before the Version Packages cut.
In whats-new-in-3-3.mdx, under "Delivery data offline sellers actually have", after "Structured DOOH location":
- **DOOH impression basis (experimental, `media_buy.dooh_impression_basis`, [#8736](https://github.com/adcontextprotocol/adcp/pull/8736)).** DOOH placements, forecast points, and delivery rows can say what kind of number `impressions` is: `currency_measured`, `seller_modeled`, `sensor_measured`, or `hybrid`, with the `audience_multiplier` applied to plays. A row whose plays used different tiers reports `impression_basis_breakdown` instead of one tier. Tiers are different units, so compare impressions within a tier. See [Impression basis](/docs/creative/channels/dooh#impression-basis-experimental).
In the same file, add media_buy.dooh_impression_basis to "New feature ids are …".
In release-notes.mdx, append "; experimental DOOH impression basis, media_buy.dooh_impression_basis (#8736)" to the 3.3 Channels bullet. Add this row to "Experimental surfaces in 3.3":
| `media_buy.dooh_impression_basis` | `impression_basis`, `audience_multiplier`, `basis_metric`, and `impression_basis_breakdown[]` on `dooh_metrics` and forecast points; the planned tier on `dooh_placement_attributes` (#8736) | New in 3.3; experimental | `impression_basis` becomes required for the `sales-dooh` claim in 4.0. |
In migration/3-2-to-3-3.mdx, under "Commercial and targeting experiments":
- **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 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.
3. Rebase onto whichever of #8736 and #8866 lands first.
Optional, not blocking
- If #8866 merges first, the same three fields could go on
canonical-forecast-point.json. That would bring the forecast basis tolist_productsand the proposal tasks in 3.3, not onlyget_products. If it doesn't fit by Thursday, it can wait. - The negative vectors assert only
valid === false. Asserting the failing keyword (minItems,not) would stop a vector from passing for the wrong reason later. - Add
core/impression-basis-breakdown-entry.jsontoindex.json, like the other 3.3 item schemas.
What I ran
The base was main df2446f + cc6f42d:
node tests/schema-validation.test.cjs: passed.- The DOOH suite: 18/18.
- Eleven related suites pass 194/194:
x-added-in-3-3-sweep,canonical-forecast-point-parity,lint-schema-enum-drift,metric-identity-coherence,print-metrics,dooh-allocation,placement-catalog-schema,delivery-projection,outcome-target,lint-additive-minorandlint-schema-required-declared. json-schema-validation: passed.docs-json-field-audit --check: passed.lint:schema-links: passed.lint-additive-minor:0 newagainst 3.2.10.
With #8866 also merged: the lint and suites listed above.
🤖 Generated with Claude Code
adcontextprotocol#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.
|
Thanks @bokelley. The three items are in (04ec164):
The optional ones too: each negative vector now checks the keyword it fails on, and The same fields on |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@aymeric45 I merged
The release notes, the what's-new page, the 3.2→3.3 migration guide, the schemas and the 3.3 sweep test merged cleanly. Locally, |
There was a problem hiding this comment.
Ladon verdict: Escalate to human review
Escalate — gated schema paths require human/CODEOWNERS approval.
This PR modifies and adds files under static/schemas/source/**, which are under a hard, deterministic approval gate (gated_paths: true). The required review status is REVIEW_REQUIRED, not APPROVED, so the gate is not satisfied and the PR cannot be auto-approved (decision table row 2).
The reviewer found the change to be clean: an experimental, additive DOOH impression-basis feature (media_buy.dooh_impression_basis, #7253) with a correct minor changeset, all new fields optional and x-status: experimental on open schemas, no new oneOf, no dist/** mutation, schema↔docs coherence verified across all surfaces, and cross-field invariants covered by tests. No Critical/High/Medium findings. On the merits this diff is approvable, but the gate holds until a human/CODEOWNERS approval lands.
Escalation reasons:
- Touches gated schema files requiring human/CODEOWNERS review:
static/schemas/source/core/canonical-placement.json,delivery-metrics.json,forecast-point.json,placement.json,index.json, and new filesimpression-basis-breakdown-entry.json,enums/impression-estimation-basis.json.review_decisionisREVIEW_REQUIRED— approval required before merge.
Why human review
- Gated paths touched (static/schemas/source/**) with review_decision=REVIEW_REQUIRED — human/CODEOWNERS approval required before merge (decision table row 2).
- This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/canonical-placement.json (modified) matches
static/schemas/source/**; static/schemas/source/core/delivery-metrics.json (modified) matchesstatic/schemas/source/**; static/schemas/source/core/forecast-point.json (modified) matchesstatic/schemas/source/**; static/schemas/source/core/impression-basis-breakdown-entry.json (added) matchesstatic/schemas/source/**; static/schemas/source/core/placement.json (modified) matchesstatic/schemas/source/**; static/schemas/source/enums/impression-estimation-basis.json (added) matchesstatic/schemas/source/**; static/schemas/source/index.json (modified) matchesstatic/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.
bokelley
left a comment
There was a problem hiding this comment.
Approving on 4ab3ab5. Items 1–3 from my Nov 11 review landed in 04ec164, and the merge of main changed nothing in the PR itself. All checks are green. Thanks @aymeric45, this ships in the 3.3 RC.
|
@KonstantinMirin could you approve this one too for Monday's RC? I approved it, but the merge-main commit went out under my account, so the last-push rule needs a second approver. All 63 checks are green and no threads are open. The merge commit only brings in main. |
KonstantinMirin
left a comment
There was a problem hiding this comment.
I'd like to approve this for the RC once everything below lands: the forecast fields on canonical-forecast-point.json, the three mechanical fixes and the wording fixes. The rest matches the Nov 7 brief, each negative vector fails for one reason, and the suites pass. Thank you, @aymeric45, for such a careful implementation.
The blocking item. The three fields exist only on forecast-point.json, which list_products and the proposal tasks don't use. Main's own 3.3 rule says "3.3 adds no field that exists only on a deprecated task" (pricing-models.mdx:795). That rule came with the #8501 withdrawals, after the Nov 11 review listed this mirror as optional. You mentioned the commit is ready, and #8866 has merged, so it can ride on the push that resolves the new package.json conflict.
Mechanical fixes, before the RC:
- Breakdown
playsandimpressionsare integers but must "sum exactly" tonumberfields:impressions.mid: 14400.5has no conformant breakdown. - The entry schema says impressions are "plays × audience multiplier", while the row text says "≈". The fixture's 21340 × 18.64 = 397,777.6, not 397,808. Making
impressionsauthoritative and the multiplier its rounded ratio settles it. - The venue multiplier divides by
loop_plays, but the row multiplier divides byplays, which the schema calls distinct counts.
Wording fixes, before the RC (exact text and line numbers in these notes):
basis_metric: name the row carryingvendor_metric_values; say whether totals and package rows carry it.- "seller-operated sensors": cover vendor-supplied sensors on the seller's screens.
- "compare within a tier": for
sensor_measured, also within the samebasis_metric. dooh.mdx: one sentence on how the tier relates to OpenRTBqty.sourcetype.- The changeset: name the three forecast fields.
- The canonical placement descriptions: match the legacy ones.
- Tests: validate the fixtures against the canonical schemas too.
Analyzed and generated with the help of Claude, fully reviewed by me.
# Conflicts: # package.json
|
@KonstantinMirin this needs your approval for the RC; the details are in #8915 (#8915). I merged main in again today (356c842), and the only conflict was the |
|
@aymeric45 the 3.3 RC is cut Monday, and #8736 is close. @KonstantinMirin's Nov 13 review (#8736 (review)) lists what's needed for approval:
Could you push these by Monday, Nov 16, 12:00 UTC? If they aren't in by then, Konstantin will push them to your branch as a maintainer change, which your "allow edits by maintainers" setting permits, so the DOOH impression basis still makes 3.3. Thank you for all the work on this. |
…ession basis (RFC adcontextprotocol#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.
|
Ladon cannot review this PR until merge conflicts are resolved. |
# Conflicts: # package.json
|
Thanks @aymeric45, the forecast fields and review fixes (546cf8b) landed before the deadline. I merged main in (384ea33) to clear the @KonstantinMirin it's ready for your review against your Nov 13 list. Brian approves after you. |
|
@aymeric45, a question on the venue rows before I finish the review: is a per-venue If AiOO doesn't need it, |
|
Thanks @KonstantinMirin. Agreed:
|
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.
KonstantinMirin
left a comment
There was a problem hiding this comment.
Approving at 9ae366dff4: every point of my Nov 13 review is addressed. Thank you, @aymeric45.
canonical-forecast-point.jsonnow carries the three fields and thedependenciesexclusion, identical to the legacy point, and the fixtures validate against the canonical product and forecast schemas.- Breakdown counts are
number,impressionsis authoritative with the multiplier as its rounded ratio, and the test checks rounding instead of a tolerance. - All the wording notes landed, including the
qty.sourcetypebullet indooh.mdx. Each negative vector still fails with exactly one error, the canonical ones included. - As agreed above,
9ae366dff4givesvenue_breakdown[]rowsplaysinstead of a multiplier, one per screen that played the spot. It also drops the currency-terms reason, so the multiplier is simply optional oncurrency_measured.
test:schemas, the DOOH tests and lint:additive-minor pass.
Non-blocking, for a later push if convenient: both forecast points say "within the same metric", but a forecast point carries no basis_metric. Naming the sensor metric the forecast plans on, or dropping the clause, would read more clearly.
bokelley
left a comment
There was a problem hiding this comment.
Approving on 9ae366d, after @KonstantinMirin's approval. The forecast fields are on canonical-forecast-point.json, and the mechanical and wording fixes landed. Thanks @aymeric45. This ships in 3.3.
Resolve conflicts in the 3.2-to-3.3 migration guide, the What's new page and the test:schemas list: take main's rc.0 text and add the DOOH entries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pick up adcontextprotocol#8854 and adcontextprotocol#9070; resolve the test:schemas list conflict. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
75a1001
The 3.3.0-rc.1 Version Packages head b46ec2e was generated on 61a1638 (#8736). #9080 merged afterwards without a changeset, so the bot never regenerated the PR, and #9073 was squash-merged as 32a90ee on base 5eb0b20 with a tree that differs from the reviewed head. Release run 44300240363 quarantined it at the provenance gate. Following RELEASING.md "Superseding an unpublishable committed prerelease", bind the committed candidate in a reviewed .changeset/release-supersession.json (release merge, committed tarball digest, reason, pending changeset pool), add the patch changeset that advances the line to 3.3.0-rc.2, and mark 3.3.0-rc.1 unpublished in the build, server and CDN worker release-status maps and the committed discovery index. The rc.1 schema, compliance and protocol bytes are unchanged. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Experimental DOOH impression basis for 3.3 (#7253), feature id
media_buy.dooh_impression_basis. A DOOHimpressionsfigure isplays × audience multiplier. This PR lets a seller say where the multiplier comes from.impression-estimation-basis:currency_measured,seller_modeled,sensor_measured,hybrid.dooh_metrics):impression_basis,audience_multiplier,basis_metric(thevendor_metric_values[]row the sensor audience comes from), andimpression_basis_breakdown[]for rows that mix tiers.list_products, proposal tasks):impression_basis,audience_multiplierandimpression_basis_breakdown[], outsidemetrics.dooh_placement_attributes): the planned tier and multiplier.dooh.mdx, the 3.3 release docs,experimental-status.mdx.All fields are optional and experimental.
impressionsis authoritative; the multiplier isimpressions / plays, rounded.Rows mixing tiers
Some rows mix tiers: a package with screens that have a sensor and screens that don't, or a sensor that stopped reporting for part of the flight. Such a row has no
impression_basis. It reports a breakdown instead:seller_modeled;The schema rejects a one-entry breakdown and a row with both fields. The test checks that tiers are distinct, which draft-07 cannot express.
Decided in the WG brief (Nov 7)
hybrid.sensor_measuredandhybrid, optional oncurrency_measured.impression_basisbecomes required for thesales-doohclaim in 4.0.Adopter data (AiOO, 30 days to Nov 3)
Testing
tests/dooh-impression-basis.test.cjs(19 tests) validates three fixtures, discovery, forecast and delivery, scaled down from one AiOO campaign with fictional names, against both theget_productsand the canonical schemas. It checks the sums, the multipliers, the parent totals and thebasis_metriclink. Each negative vector checks the rule it breaks. The related suites,test:additive-minor(0 new) and the doc checks pass.Follow-ups
sales-doohstoryboard assertions in 4.0, including distinct tiers, which draft-07 cannot check.