diff --git a/.changeset/withdraw-get-products-sync-creatives-deprecated-fields.md b/.changeset/withdraw-get-products-sync-creatives-deprecated-fields.md new file mode 100644 index 00000000000..6dce4b1decd --- /dev/null +++ b/.changeset/withdraw-get-products-sync-creatives-deprecated-fields.md @@ -0,0 +1,21 @@ +--- +"adcontextprotocol": minor +--- + +Withdraw the 3.3 additions to the deprecated `get_products` task and the deprecated `sync_creatives` `assignments[]` row, and move execution readiness to `list_products` (adcp#8501, entries 20–25 and the `get_products` rows of the deprecated-task table). 3.3 adds no field that exists only on a deprecated task. Where a live task lacks the capability, it moves there or waits for 4.0. + +**All of these shipped in 3.3 betas and are removed after `3.3.0-beta.5`.** This is a beta-to-beta change, not a change to a stable release. The betas are immutable, so a seller or SDK built from a beta bundle has the surfaces below to remove. + +**Exact-package forecasts on `get_products` (#8468, beta.1 to beta.5).** Removed: `refine[].package`, `media-buy/package-forecast-input.json`, the request rule tying `package` to `buying_mode: "refine"` and to non-finalize entries, and `refinement_applied[]` `result_product_id`, `resolved_start_time` and `resolved_end_time` with their `applied` rule. `refinement_applied` is optional again for every request. The forecast has no 3.3 home; where it belongs on the compact lifecycle is an open working-group question. + +**`get_products` `filters.target_audiences` (#8215, experimental, beta.1 to beta.5).** Removed from `core/product-filters.json`, with its `dependencies` entry. It is planned for `list_products` `offer_filters` and `buy_products` purchases in 4.0 (`purchase_target_audiences_required_in_4_0`). + +**Collection cards on `get_products` (#8141, experimental, beta.0 to beta.5).** Removed: the `include_collections` request flag, the response-level `collections` array and its `dependencies` entry, the `collections` branch of `get-products-rejected.json`, and `include_collections` in the `wholesale_feed_version` scope. `list_products`, `request_proposals` and `refine_proposals` keep both. + +**Execution readiness (#7934, experimental, beta.1 to beta.5) moves to `list_products`.** `include_execution_readiness` leaves the `get_products` request and the `execution_readiness` map leaves its response. Both are added to the open `list_products` request and response, with the same shape and rules; the map is versioned independently of `feed_version` and is absent on an `unchanged` outcome. The `media_buy.execution_readiness` storyboard now drives `list_products`. `binding_field` now names the `buy_products` paths, `purchases[].optimization_goals[].event_sources[].event_source_id` and `purchases[].catalog_ids[]`, instead of the legacy `create_media_buy` `packages[]` paths, and `execution_requirements` documents the purchase binding beside the legacy one. + +**`price_adjustments` on `get_products` pricing options (#7955, experimental, beta.1 to beta.5).** Removed from the `cpm`, `vcpm`, `cpc`, `cpcv`, `cpv`, `cpp` and `flat_rate` options with their `dependencies`, along with `pricing-options/price-adjustments.json`, `error-details/price-adjustments-mismatch.json`, the product rule that a placement-selection row requires `overlay_support.placement_selection`, the `price_adjustments_resolution` verifier constraint on `product-purchase.json`, and the `price-adjustments` test vectors. A seller stops listing `media_buy.price_adjustments`. The design is kept for the canonical pricing option in 4.0 (`canonical_price_adjustments_required_in_4_0`). + +**`sync_creatives` `assignments[]` `landing_page_url` and `trackers` (#8180, #8220, beta.0 to beta.5).** Removed from the deprecated row, which now rejects them by name. The `assignment_operations` `assign` operation keeps both. + +The consumed changesets for these PRs stay in `.changeset/pre/` as history. The 3.3 release notes, What's new, the 3.2 to 3.3 migration guide, and the 3.3 beta page say what to remove under "Withdrawn from the deprecated tasks". diff --git a/docs/building/by-layer/L3/error-handling.mdx b/docs/building/by-layer/L3/error-handling.mdx index 66ddedc5a1f..feb6fe0e595 100644 --- a/docs/building/by-layer/L3/error-handling.mdx +++ b/docs/building/by-layer/L3/error-handling.mdx @@ -533,7 +533,7 @@ The wire-level `recovery: "correctable"` on the sandbox-only path is the registe | [`AUDIENCE_TOO_SMALL`](/docs/building/verification/compliance-catalog#error-code-audience-too-small) | correctable | Audience segment below minimum size | Broaden targeting or upload more audience members | {/* /schemas/latest/ link: schema unreleased; switch to the v3 alias after the next release. */} -For `UNSUPPORTED_FEATURE` rejecting an unsupported or removed targeting dimension, details SHOULD follow [`error-details/unsupported-targeting-dimension.json`](https://adcontextprotocol.org/schemas/latest/error-details/unsupported-targeting-dimension.json); see [Rejected targeting dimensions](/docs/media-buy/advanced-topics/targeting#rejected-targeting-dimensions). For an `INVALID_REQUEST` that rejects a buyer-supplied `pricing` differing from the price a `price_adjustments` table resolves to, details SHOULD follow [`error-details/price-adjustments-mismatch.json`](https://adcontextprotocol.org/schemas/v3/error-details/price-adjustments-mismatch.json). For `REQUOTE_REQUIRED`, details SHOULD follow [`error-details/requote-required.json`](https://adcontextprotocol.org/schemas/v3/error-details/requote-required.json). For [`ACTION_NOT_ALLOWED`](/docs/building/verification/compliance-catalog#error-code-action-not-allowed) with `reason: "not_supported_on_buy"`, the existing [`error-details/action-not-allowed.json`](https://adcontextprotocol.org/schemas/v3/error-details/action-not-allowed.json) shape also permits `decline_reason`. Sellers SHOULD emit the coarse reason when they have a structured seller-policy classification and disclosure does not expose private thresholds or enforcement controls. Buyers MUST tolerate its absence and MUST NOT infer that an undisclosed policy does not exist. Structural action denials SHOULD omit it. +For `UNSUPPORTED_FEATURE` rejecting an unsupported or removed targeting dimension, details SHOULD follow [`error-details/unsupported-targeting-dimension.json`](https://adcontextprotocol.org/schemas/latest/error-details/unsupported-targeting-dimension.json); see [Rejected targeting dimensions](/docs/media-buy/advanced-topics/targeting#rejected-targeting-dimensions). For `REQUOTE_REQUIRED`, details SHOULD follow [`error-details/requote-required.json`](https://adcontextprotocol.org/schemas/v3/error-details/requote-required.json). For [`ACTION_NOT_ALLOWED`](/docs/building/verification/compliance-catalog#error-code-action-not-allowed) with `reason: "not_supported_on_buy"`, the existing [`error-details/action-not-allowed.json`](https://adcontextprotocol.org/schemas/v3/error-details/action-not-allowed.json) shape also permits `decline_reason`. Sellers SHOULD emit the coarse reason when they have a structured seller-policy classification and disclosure does not expose private thresholds or enforcement controls. Buyers MUST tolerate its absence and MUST NOT infer that an undisclosed policy does not exist. Structural action denials SHOULD omit it. **Implementation note (non-normative).** Repeated out-of-envelope controls can be used to map a seller's exact share-of-voice, notice-window, frequency, or commitment thresholds. Consider rate-limiting these deterministic probes using the same posture as [`refine_proposals`](/docs/media-buy/product-discovery/proposal-negotiation#log-for-audit-without-leaking-terms), and omit `decline_reason` when even the coarse category would disclose sensitive enforcement logic. diff --git a/docs/creative/channels/broadcast.mdx b/docs/creative/channels/broadcast.mdx index e41d1643c12..a972e8f2755 100644 --- a/docs/creative/channels/broadcast.mdx +++ b/docs/creative/channels/broadcast.mdx @@ -227,7 +227,7 @@ This works today with four gaps. Read them before building on it: - **The demo is bound on the forecast, not on the price.** A CPM pricing option has no demographic parameters, unlike a CPP option (`parameters.demographic_system`, `demographic`). `measurement_terms.billing_measurement` binds the vendor, the window, and the variance, but has no demographic field. - **The guaranteed volume has no typed definition.** `purchases[].impressions` is the contracted volume, and a buyer can require a floor on it with `refine_proposals` `constraints.impressions` (a hard minimum summed across purchases). The schema does not say that number counts measured audience, in which demo, from which vendor, or on which window. Those facts sit on the forecast and `billing_measurement`, and the forecast is outside `commercial_terms`, so it is not covered by `terms_digest`. Treat the demo as a term agreed in the human contract outside AdCP, not one a protocol agent can verify. -- **:30 equivalization is only partly expressible.** Rate-side spot-length indexing is expressible through [`price_adjustments`](/docs/media-buy/advanced-topics/pricing-models#selection-dependent-price-adjustments) (a rate row keyed to the spot's format option). Impression-side :30 equivalization and demo-bound CPM remain open and are tracked for 3.4 in [#8001](https://github.com/adcontextprotocol/adcp/issues/8001). Nothing declares whether a :15 impression counts as half a :30 unit or the factor to apply, so on a buy that mixes :15 and :30 spots the impression-side rule is a term to settle outside the protocol. +- **:30 equivalization is not expressible.** Rate-side spot-length indexing needs a separately priced option or product per spot length; a rate table for it is [planned for 4.0](/docs/reference/migration/v4-compatibility#canonical_price_adjustments_required_in_4_0). Impression-side :30 equivalization and demo-bound CPM remain open and are tracked for 3.4 in [#8001](https://github.com/adcontextprotocol/adcp/issues/8001). Nothing declares whether a :15 impression counts as half a :30 unit or the factor to apply, so on a buy that mixes :15 and :30 spots the impression-side rule is a term to settle outside the protocol. - **No under-delivery trigger, and the schedule on the wire is experimental.** `makegood_policy` does not name a volume shortfall as a trigger. A seller may report the planned schedule as `scheduled` rows in `by_spot`, but that field is experimental and seller-declared, so a buyer cannot assume one. See [Makegoods](#makegoods). diff --git a/docs/creative/task-reference/sync_creatives.mdx b/docs/creative/task-reference/sync_creatives.mdx index f9fcc3a88c4..5f82cdcc45e 100644 --- a/docs/creative/task-reference/sync_creatives.mdx +++ b/docs/creative/task-reference/sync_creatives.mdx @@ -154,7 +154,7 @@ A product can declare a separate `creative_policy.review_sla` for time to an app | `idempotency_key` | string | Yes | Client-generated key that makes retries safe. Use a fresh UUID or other unique value per request. | | `creatives` | Creative[] | Conditional | Creative assets to upload/update (max 100); at least one of `creatives`, `assignments`, or `assignment_operations` is required. | | `creative_ids` | string[] | No | Optional filter to limit sync scope to specific creative IDs. Only these creatives are affected, others remain untouched. Useful for partial updates and error recovery. | -| `assignments` | array | No | Deprecated additive `{creative_id, package_id}` shorthand. Optional `weight`, `placement_ids`, and capability-gated `landing_page_url` and `trackers` per assignment. | +| `assignments` | array | No | Deprecated additive `{creative_id, package_id}` shorthand. Optional `weight` and `placement_ids` per assignment. It does not carry `landing_page_url` or `trackers`; send those on an `assign` operation. | | `assignment_operations` | array | Conditional | Ordered `assign`, `unassign`, or `replace` operations for existing creative IDs, without requiring creative uploads. Only `assign` accepts capability-gated `landing_page_url` and `trackers`; `replace` transfers the replaced assignment's settings, including those, to the replacement ([Replacing a creative on a package](#replacing-a-creative-on-a-package)). The request is atomic and requires strict validation. | | `dry_run` | boolean | No | When true, rehearse this exact sync operation without applying it (default: false). Use this for seller trafficking acceptance checks; use [`validate_input`](https://adcontextprotocol.org/schemas/v3/creative/validate-input-request.json) for manifest-only preflight against canonical/product format targets. | | `validation_mode` | string | No | Validation strictness: `"strict"` (default) or `"lenient"` | @@ -166,11 +166,15 @@ seller rejects the request rather than applying last-write-wins behavior. ### Assignment landing pages -In AdCP 3.3, optional `landing_page_url` on `assignments[]`, the `assign` variant of `assignment_operations[]`, and package `creative_assignments` in [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) replaces the click-through destination for that one creative on that one package. The library creative does not change. The override applies to every click-through destination for that assignment, including per-state destinations; the seller MUST serve it everywhere it applies or reject the assignment through existing assignment errors, and MUST NOT silently ignore it or apply it partially. This includes clicks embedded in HTML, JavaScript, or a VAST tag that the seller cannot override. The creative's approval stands; a seller that reviews destinations reviews the assignment, not the creative. + +The deprecated `assignments[]` row does not carry `landing_page_url` or `trackers`. The 3.3 betas accepted both there; they are withdrawn from that row before 3.3 GA ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)), and the row rejects them by name. Send them on an `assignment_operations` `assign`. + + +In AdCP 3.3, optional `landing_page_url` on the `assign` variant of `assignment_operations[]`, and package `creative_assignments` in [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) replaces the click-through destination for that one creative on that one package. The library creative does not change. The override applies to every click-through destination for that assignment, including per-state destinations; the seller MUST serve it everywhere it applies or reject the assignment through existing assignment errors, and MUST NOT silently ignore it or apply it partially. This includes clicks embedded in HTML, JavaScript, or a VAST tag that the seller cannot override. The creative's approval stands; a seller that reviews destinations reviews the assignment, not the creative. Buyers MUST NOT send the field unless [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) declares `creative.supports_assignment_landing_page: true` (default false, requiring `has_creative_library: true`); an agent without that capability MUST reject the field with [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature). The URL may contain [AdCP macros](/docs/creative/universal-macros) under the same rules as the creative's own click-through without declarations, including the existing 3.x compatibility behavior. This field introduces no assignment-level `macro_declarations`; declarations on the original creative assets do not transfer to the override, and neither URL syntax nor this capability proves declared token resolution. Existing governed catalog substitution and encoding rules still apply. -On additive `assignments[]` upserts and `assign` operations, omitting `landing_page_url` preserves an existing override. To restore inheritance without changing the library creative, atomically `unassign` then `assign` the same creative/package without the field; include any weight, placement settings, or assignment trackers that must remain on the new assignment. `null` is not accepted. For a complete `update_media_buy` package `creative_assignments` replacement, omission from a supplied assignment row restores inheritance; omitting the entire replacement array leaves assignments unchanged. +On `assign` operations, omitting `landing_page_url` preserves an existing override. To restore inheritance without changing the library creative, atomically `unassign` then `assign` the same creative/package without the field; include any weight, placement settings, or assignment trackers that must remain on the new assignment. `null` is not accepted. For a complete `update_media_buy` package `creative_assignments` replacement, omission from a supplied assignment row restores inheritance; omitting the entire replacement array leaves assignments unchanged. The unassign/assign reset recreates assignment state. Its `assign` operation cannot carry `rotation_mode`, `group_id`, `sequence_position`, or structured `placement_refs`. To retain those controls, use a complete `update_media_buy` package `creative_assignments` replacement instead: retain every other assignment and its authored settings, retain the target's rotation/group/placement settings and assignment trackers, and omit only the target's `landing_page_url`. Readback URLs are effective destinations, so do not blindly copy them into override fields when reconstructing authored assignment state. @@ -194,7 +198,7 @@ After checking the capability and setting an override with an `assign` operation ### Assignment trackers -In AdCP 3.3, optional `trackers` on `assignments[]`, the `assign` variant of `assignment_operations[]`, and package `creative_assignments` in [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) attaches measurement URLs to one creative on one package. A buyer can reuse a library creative across media buys while giving each assignment its own campaign and package values. The seller fires these trackers **in addition to** the creative's own trackers. Changing assignment trackers does not mutate the library creative, its revision, or its approval; any tracker policy review applies to the assignment. +In AdCP 3.3, optional `trackers` on the `assign` variant of `assignment_operations[]`, and package `creative_assignments` in [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) and [`update_media_buy`](/docs/media-buy/task-reference/update_media_buy) attaches measurement URLs to one creative on one package. A buyer can reuse a library creative across media buys while giving each assignment its own campaign and package values. The seller fires these trackers **in addition to** the creative's own trackers. Changing assignment trackers does not mutate the library creative, its revision, or its approval; any tracker policy review applies to the assignment. Buyers MUST NOT send `trackers` unless [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) declares `creative.supports_assignment_trackers: true`. This capability defaults to false and requires `has_creative_library: true`; an unsupported agent MUST reject the field with [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature). It is independent of `creative.supports_assignment_landing_page`. @@ -215,7 +219,7 @@ These limits apply only when the effective format declares at least one tracker Tracker URLs use the existing [macro-bearing URL rules](/docs/creative/universal-macros#template-syntax) without declarations, including 3.x compatibility behavior. Declarations on creative assets do not transfer to these URLs. Neither URL syntax nor assignment tracker support guarantees resolution of any particular macro; check the seller's macro resolution capabilities. Buyers can put their own known buy/package values directly in the URL, avoiding a dependency on seller ID substitution. Readback preserves the accepted templates. -Supplying `trackers` replaces that assignment's previous tracker list; it does not append on each upsert or retry. Omission on additive `assignments[]` upserts or `assign` operations preserves the list. To clear it, use the atomic `unassign`/`assign` [reset recipe](#assignment-landing-pages), omitting `trackers` from the new assignment and resupplying other authored settings, including any landing-page override. For rotation/group/structured placement controls, use a complete `update_media_buy` package `creative_assignments` replacement, retaining every other assignment and setting, and omitting only the target's `trackers`. Omission from a supplied replacement row clears its assignment trackers; omitting the entire replacement array leaves assignments unchanged. Empty arrays and `null` are not accepted on writes. +Supplying `trackers` replaces that assignment's previous tracker list; it does not append on each upsert or retry. Omission on `assign` operations preserves the list. To clear it, use the atomic `unassign`/`assign` [reset recipe](#assignment-landing-pages), omitting `trackers` from the new assignment and resupplying other authored settings, including any landing-page override. For rotation/group/structured placement controls, use a complete `update_media_buy` package `creative_assignments` replacement, retaining every other assignment and setting, and omitting only the target's `trackers`. Omission from a supplied replacement row clears its assignment trackers; omitting the entire replacement array leaves assignments unchanged. Empty arrays and `null` are not accepted on writes. Supporting sellers MUST return `trackers` in [`list_creatives`](/docs/creative/task-reference/list_creatives) `assignments.assigned_packages[]` and [`get_media_buys`](/docs/media-buy/task-reference/get_media_buys) `packages[].creative_approvals[]`. Return the complete assignment-scoped list, preserving events, URL templates, order, and duplicate occurrences, or `[]` when there are no assignment trackers. This list excludes the creative's own trackers, which remain in its `assets` and also fire. Buyers can copy a nonempty list back as authored assignment state without duplicating the creative's trackers; use the reset recipe for an empty readback list. After an assignment `merge`, the buyer creative's package assignment trackers apply alongside that creative's trackers; the seller MUST validate the resulting combination or reject the atomic merge. diff --git a/docs/media-buy/advanced-topics/pricing-models.mdx b/docs/media-buy/advanced-topics/pricing-models.mdx index 53b85d9fc60..7d13b85301e 100644 --- a/docs/media-buy/advanced-topics/pricing-models.mdx +++ b/docs/media-buy/advanced-topics/pricing-models.mdx @@ -676,7 +676,7 @@ For amount-based discounts: running = running − amount Operator fees use the fee formulas. -All monetary values are rounded to the precision of the currency (e.g., 2 decimal places for EUR/USD) at each step, or, for an option that declares [`price_adjustments`](#selection-dependent-price-adjustments), to that option's price precision, which can be finer. The invariant holds after rounding. +All monetary values are rounded to the precision of the currency (e.g., 2 decimal places for EUR/USD) at each step. The invariant holds after rounding. Example with mixed adjustments: @@ -790,116 +790,11 @@ A flat per-campaign fee or retainer is not a per-unit adjustment and is out of s --- -## Selection-dependent price adjustments +## Selection-dependent price adjustments (withdrawn) - -Experimental (`media_buy.price_adjustments`): sellers that implement `price_adjustments` declare the feature id in `experimental_features`, and the shape may change in 3.x with the notice described in [Experimental status](/docs/reference/experimental-status). The rule that a seller MUST NOT return a table to callers below 3.3 applies in addition. - +The 3.3 betas (`3.3.0-beta.1` through `3.3.0-beta.5`) let a fixed-price option on the deprecated `get_products` publish an experimental `price_adjustments` table (`media_buy.price_adjustments`, [#7955](https://github.com/adcontextprotocol/adcp/pull/7955)), so a buyer could compute the binding rate for its format option and placement selections and its flight dates. It is withdrawn before 3.3 GA ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)): 3.3 adds no field that exists only on a deprecated task, and the canonical pricing option is closed in 3.x. The design is planned for the canonical pricing option in 4.0; see [Canonical pricing options carry price adjustments](/docs/reference/migration/v4-compatibility#canonical_price_adjustments_required_in_4_0). -### Two supported paths - -A seller can quote a price in either of two equally supported ways: - -- **A fully priced offer.** The seller returns a pricing option, or a configured product or proposal, whose `fixed_price` is the price for what was quoted. It publishes no table. The price applies only to that quote: the buyer cannot derive the price of a different selection, date range, or volume from it and re-discovers or refines to learn it. -- **A fixed price plus an adjustment table.** A fixed-price `cpm`, `vcpm`, `cpc`, `cpcv`, `cpv`, `cpp`, or `flat_rate` option declares an ordered `price_adjustments` table, so the buyer can compute the price locally for the selections and dates the table covers. - -Declaring a table is optional and a fully priced offer is not a fallback. Whether a table is present tells the buyer whether it can compute the price itself. Many sellers, broadcast included, price the combination of property, dates, and format against avails and their own yield rules, and a seller managing yield this way SHOULD NOT be expected to publish a table or the method behind its prices. A table suits sellers whose rate really is a base rate with coefficients: Dutch linear TV rate cards multiply a net base price by month, spot-length, target-audience, and market indices. - -### Rows and composition - -`fixed_price` stays the **base rate**: it is what the buyer pays when no row applies, and it is already net of any negotiated discount in the option's own `price_breakdown`. This is distinct from `eligible_adjustments` (which kinds of adjustment are possible) and from `price_breakdown` (how a negotiated price was derived): `price_adjustments` is the seller's declared, binding function from selections and dates to price. - -Every row is a `fee` (adds) or a `discount` (subtracts), carrying exactly one of: - -- a **`rate`**: a proportion of the running total at that step. A fee `rate` can be 1 or more, so an index of 2.5 is a fee `rate` of 1.5; -- an **`amount`**: a fixed amount in the option's currency per pricing unit. - -There is no separate index row kind. A Dutch index card factor `f` is a fee `rate` of `f − 1` when `f > 1`, a discount `rate` of `1 − f` when `f < 1`, and no row when `f = 1`. The rate form needs no second kind, one rule covers percentage fees, discounts, and index cards, and a row means the same thing wherever it sits in the table. - -Each row has a `dimension`. `format_option` and `placement_selection` rows match values the buyer selects; `always` rows need no selection and apply whenever their window allows (month, market, and audience indices). - -```json -{ - "pricing_option_id": "oranje_grp_eur_2026", - "pricing_model": "cpp", - "currency": "EUR", - "fixed_price": 1000.00, - "parameters": { "demographic": "A25-54" }, - "price_adjustments": [ - { "dimension": "always", "kind": "fee", "name": "month_index_nov", "rate": 0.10, - "valid_from": "2026-11-01T00:00:00+01:00", "valid_until": "2026-12-01T00:00:00+01:00" }, - { "dimension": "always", "kind": "discount", "name": "market_index_nov", "rate": 0.05, - "valid_from": "2026-11-01T00:00:00+01:00", "valid_until": "2026-12-01T00:00:00+01:00" }, - { "dimension": "format_option", "format_option_ref": { "scope": "product", "format_option_id": "spot_20s" }, - "kind": "discount", "name": "spot_length_20s", "rate": 0.20 }, - { "dimension": "always", "kind": "fee", "name": "target_audience_a25_54", "rate": 0.25 }, - { "dimension": "placement_selection", - "placement_ref": { "publisher_domain": "oranjetv.example", "placement_id": "first_in_break" }, - "kind": "fee", "name": "first_in_break_premium", "rate": 0.20 } - ] -} -``` - -A buyer booking a 20-second spot in first position for a flight in the second half of November pays, applying each row to the running total in declared order: `1000.00 → 1100.00` (month index 1.10) `→ 1045.00` (market index 0.95) `→ 836.00` (20-second index 0.80) `→ 1045.00` (audience index 1.25) `→ 1254.00` (first-in-break fee of 20% of the running total, `209.00`). The accepted `price_breakdown` lists the five rows in that order: fee `0.10`, discount `0.05`, discount `0.20`, fee `0.25`, fee `0.20`. - -Rate-side spot-length indexing is expressible through [`price_adjustments`](#selection-dependent-price-adjustments) (a row keyed to the spot's format option). Impression-side :30 equivalization and demo-bound CPM remain open and are tracked for 3.4 in [#8001](https://github.com/adcontextprotocol/adcp/issues/8001). - -### Eligible dimensions - -Selection rows price only values that come from a seller-published catalog on the same product, so the seller can enumerate them in advance. The dimensions in this version are placement and format option (which carries spot length): - -| `dimension` | Row selector | Matches when | -|---|---|---| -| `format_option` | `format_option_ref` | The purchase's `format_option_refs` includes the reference. It MUST resolve to a format option the product declares. | -| `placement_selection` | `placement_ref` | A `mode: "selected"` `placement_selection` includes the placement. It MUST resolve to a targetable placement of the product, and the product MUST declare `overlay_support.placement_selection`. | -| `always` | none | Always, subject to the row's window. | - -Matching is full-identity equality after resolving both sides to the product's declared entry: a legacy placement ref and a placement identity for the same placement match, a seller-inline placement's `seller_agent.agent_url` compares under the [URL canonicalization rules](/docs/reference/url-canonicalization) rather than byte equality, and the same format option ID under a different `scope` does not. Only values the buyer actually selects match a selection row. Omitting the selection, or choosing the product default, matches no row. - -**Property and collection are out of this version.** `property_list` and `collection_list` are buyer-owned references (`agent_url` plus `list_id`): the buyer creates and changes the list, so the seller has no catalog entry to anchor a row to and cannot publish a price for a value it cannot enumerate. A row keyed to a list would be priced by the buyer's own list contents. A seller that prices property or collection differently quotes them as a fully priced offer for the properties or collections the buyer names, or sells them as separately priced products. A later minor version can add property by seller-side id, or collection by `collection_id`, once a row can name a value the seller publishes. - -Position in break is modelled as a seller-published placement (the example above prices `first_in_break` that way) until the booking half of [#8009](https://github.com/adcontextprotocol/adcp/issues/8009) lands; the reporting side is a separate contract ([Position pricing is outside this reporting contract](/docs/media-buy/media-buys/optimization-reporting)). Activation method, measurement vendor, and reporting tier have no selectable anchor yet; an unknown `dimension` is a schema error and later minor versions add values as anchors appear. - -### Validity windows - -A row may carry `valid_from` (inclusive) and `valid_until` (exclusive), both date-times with an offset, so a seller whose month and market indices change monthly publishes one row per window. A row without them always applies. The window is evaluated at the purchase's `start_time`. - -A purchase resolves to **one** price, so a flight whose `[start_time, end_time)` crosses a `valid_from` or `valid_until` of a row that would otherwise apply is rejected with [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) naming the flight. The buyer splits the flight into one purchase per window. A flight may end exactly on a `valid_until`. Resolving each installment or each day of one purchase at its own rate would need a price per installment in the accepted snapshot, which this version does not define. - -Row windows are separate from quote expiry below: a window says when a rate is in force, expiry says how long the seller holds the quote. - -### Resolution - -Sellers and buyers MUST resolve a purchase's price in this order: - -1. **Select rows.** A row applies when its window contains the purchase's `start_time` and its selector matches. Among rows of one selection dimension, only the first applicable row in declared order fires, so a seller can list the same value once per window and the matching window wins. `always` rows each fire. Sellers who want multi-select purchases priced at the highest applicable row list it first; summing the matched values of one dimension is a recorded limit of 3.3, not supported in this version. -2. **Apply in declared order to one running total.** Start the running total at `fixed_price`. For each firing row, in the order the seller declared it, a `rate` row adds (`fee`) or subtracts (`discount`) `round(running × rate)` and an `amount` row adds or subtracts its `amount`; the result is the new running total. Because each row applies to the running total, a 10% fee followed by a 10% fee gives `× 1.21`, not `× 1.20`; a fixed amount followed by a rate is scaled by the rate; and the same rows declared in another order can resolve to a different price. The seller's declared order is part of the quote. -3. **Precision.** The option's **price precision** is the greatest of the currency's ISO 4217 minor-unit exponent; 4 for `cpm`, `vcpm`, `cpc`, `cpcv`, `cpv`, and `cpp` options; and the fewest decimal places that exactly represent `fixed_price` and each row `amount`. Precision is a property of the numeric values, not of how they were written: `0.0100` and `0.01` are the same value. Every step rounds half away from zero to price precision, so the resolved price is the exact running total and is not rounded again; rounding to currency minor units belongs to later spend and invoice calculation. Implementations MUST use exact decimal or integer arithmetic. -4. **Never negative.** The total MUST NOT fall below zero at the end. Sellers MUST verify at publication that no permitted selection resolves below zero; a purchase that would is rejected with `INVALID_REQUEST`, never clamped. - -This replaces the draft's earlier model, which applied index factors multiplicatively and then added percentage premiums to the indexed price without compounding them. The two give the same price for a table that declares its index rows before at most one percentage row and its `amount` rows last, which covers the Dutch example above; they differ when two percentage rows both apply, and when an `amount` row is declared before a rate row. - -Two consequences follow from one-row-per-dimension. A multi-select purchase pays the first applicable row's rate on all of its volume, so a seller that wants each selected value priced separately sells separate packages or publishes fully resolved per-selection options. And a row that prices a placement already in the product's default set would make choosing it explicitly cost more than the default, so sellers should price only values that add to the default. - -### Quotes stay bound to their terms - -A price, whether a fully priced offer or resolved from a table, is bound to what it was quoted for: its scope, applicable dates, buyer commitments, delivery terms, and the account it was quoted to. For a table: - -- **Account.** A table applies only to the account it was returned for. A buyer MUST NOT apply a table returned for one account to another account. A response with `cache_scope: "public"` was returned for every account that prices off the public rate card. -- **Expiry.** A table expires with the quote it came in: the proposal's or offer's `expires_at`, or, for a reusable product, the validity of the discovery response it was returned in (see `pricing_version` and `cache_scope` on `get_products`). After expiry the buyer re-discovers and uses the new table; it MUST NOT price a new purchase from the expired one. -- **Without a table.** A fully priced offer carries the same bounds. Its price applies only to what was quoted, and the buyer MUST NOT extrapolate it to other selections or dates. - -### Resolved price and accepted terms - -- When `pricing` is omitted from a purchase, the seller computes the resolved price. When the buyer supplies `pricing`, the seller MUST reject any `fixed_price` or `price_breakdown` that differs from the resolved result with [`INVALID_REQUEST`](/docs/building/verification/compliance-catalog#error-code-invalid-request) naming the pricing field, and SHOULD carry the resolved value and breakdown as [`error-details/price-adjustments-mismatch.json`](https://adcontextprotocol.org/schemas/v3/error-details/price-adjustments-mismatch.json) (`details.resolved_fixed_price`, `details.resolved_price_breakdown`), so the buyer can see which row it disagrees on. It MUST NOT silently reprice the request. -- In the accepted purchase `pricing`, the seller MUST return `fixed_price` as the resolved rate. When any row fired, the seller MUST also return `price_breakdown`: its `list_price` is the declared option's `list_price` when the option declares a `price_breakdown`, and otherwise the option's declared `fixed_price`; its `adjustments` are the declared breakdown's adjustments followed by one entry per fired row, in declared order. A rate row is recorded with its `rate` when that rate is below 1, and as its currency delta in `amount` otherwise (a fee rate of 1 or more); an amount row is recorded as its `amount`; a row whose delta rounds to zero contributes nothing and is omitted. `list_price` folded through `adjustments` equals `fixed_price`, so the invariant above covers selection-dependent pricing. A verifier re-resolves the table of the accepted `pricing_option_id` over the purchase's selections and flight and compares. -- **The accepted `pricing_option_id` pins the table.** Any change to the table, or to which selections or dates it matches, is a change to binding price and mints a new `pricing_option_id`. So the accepted `pricing_option_id`, which `commercial_terms.terms_digest` covers, identifies exactly one immutable table, unfired rows and rows for other windows included. Changes the agreement already permits (a different format option or placement within the accepted `change_terms[]`) are priced from the table of the accepted `pricing_option_id` without a re-quote. Both parties retain that table from discovery, and the seller MUST price from it, not from a later table the option's successor carries. Quote expiry does not apply once the option is accepted: the accepted ID still names the table. -- **The table grants no change rights.** Pinning the table does not make any selection or date change allowed. Which changes the buyer may make come only from the accepted `change_terms[]` ([DR-0016](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0016-proposal-bound-buyer-change-rights.md)): a change they do not permit returns `ACTION_NOT_ALLOWED` whatever the table would price it at, and a change that exceeds the accepted commercial envelope returns `REQUOTE_REQUIRED`. A seller MUST NOT read a row for an unused value as consent to that change, and a buyer MUST NOT read it as an entitlement. -- **The table is not embedded in the accepted snapshot.** The canonical schemas that carry accepted terms (`canonical-pricing-option.json`, `product-purchase.json`, and the commercial terms that contain them) are held closed until 4.0. Embedding the table in the snapshot, so the terms are self-contained without the retained discovery copy, is a 4.0 item tracked with [#8501](https://github.com/adcontextprotocol/adcp/issues/8501). - -A seller MUST NOT return an option carrying `price_adjustments` to a caller whose `adcp_version` is below 3.3, because an older buyer would read `fixed_price` as the whole price and be repriced at create; for those callers it publishes fully priced per-selection options or omits the option. A consumer that does not recognize a row's `dimension` treats the option as unpurchasable. The `fixed_price` is net of the option's declared discounts. Auction floors (`floor_price`) do not take adjustments, and `price_adjustments` requires `fixed_price`. Availability and forecasts stay seller-computed: the price resolves locally but feasibility does not. - -A seller can instead publish a fully priced pricing option per selection combination, or split the inventory into separately priced products. Both remain valid with equal standing; `price_adjustments` is for sellers whose dimensions are orthogonal enough that a combination catalog would explode and who are willing to publish the coefficients. +Until then, a seller whose rate depends on the buyer's selections publishes a fully priced option per selection combination, returns a request-specific configured product after rediscovery with concrete targeting, or splits the inventory into separately priced products. Each price applies only to what was quoted, and the buyer does not extrapolate it to other selections or dates. --- diff --git a/docs/media-buy/advanced-topics/targeting.mdx b/docs/media-buy/advanced-topics/targeting.mdx index 54af7e507ca..819f60732e0 100644 --- a/docs/media-buy/advanced-topics/targeting.mdx +++ b/docs/media-buy/advanced-topics/targeting.mdx @@ -816,10 +816,8 @@ Support guarantees selectability subject to disclosed limits, not inventory or a forecast for every possible value. A forecast returned without concrete metro values describes the product's discovery/default scope. Rediscover with the values in `targeting_overlay` for a metro-specific forecast. Fixed prices and -floors remain binding uniformly for supported selections, except for adjustments -the selected fixed-price option declares in -[`price_adjustments`](/docs/media-buy/advanced-topics/pricing-models#selection-dependent-price-adjustments); -price guidance is non-binding. If other rates vary by value, the seller returns a configured product +floors remain binding uniformly for supported selections; price guidance is +non-binding. If rates vary by value, the seller returns a configured product after concrete rediscovery, splits rate tiers into products, or exposes only non-binding guidance until concrete values are known. It never silently reinterprets a selected pricing option at a new price. diff --git a/docs/media-buy/product-discovery/collections-and-installments.mdx b/docs/media-buy/product-discovery/collections-and-installments.mdx index 21ecc932551..80bfe104813 100644 --- a/docs/media-buy/product-discovery/collections-and-installments.mdx +++ b/docs/media-buy/product-discovery/collections-and-installments.mdx @@ -126,7 +126,7 @@ A collection is a persistent, publisher-controlled content program that produces `images`, `sample_content`, `url` and `talent[].brand_ref` give a creator or show a card: a picture, samples of its content, a page to link out to, and a typed link to the person's brand identity. Sellers that populate them list `media_buy.collection_cards` in `experimental_features`. Publishers declaring collections in `adagents.json` (and registry `collection.*` events, which embed the same object) cannot list experimental features, so consumers treat these fields as experimental wherever they appear. -Collection cards reach buyers in-band. Products keep their `{publisher_domain, collection_ids}` selectors, and when the buyer sets `include_collections: true` the `get_products`, `list_products`, `request_proposals` and `refine_proposals` responses can carry a top-level `collections` array with the full object for each referenced collection (see [collections in responses](#collections-in-responses)). Sellers that list `media_buy.collection_catalog` also serve the same cards outside a brief through [`list_collections`](/docs/media-buy/task-reference/list_collections), by key or with filters, and push card changes to buyer mirrors through [collection card webhooks](/docs/media-buy/task-reference/list_collections#collection-card-webhooks). For a creator marketplace or a large podcast network this replaces fetching every publisher's `adagents.json` to draw one proposal, and it keeps fast-moving facts such as samples current. Sellers can also attach samples to the product card with the `sample_content` [reference asset role](/docs/media-buy/product-discovery/media-products#reference-assets), as a `url` asset built from `post_url` (the role cannot carry `platform`, `published_at` or `identity_ref`). Consumers skip `sample_content` entries without `post_url`, and `reference_authorization` and `identity_ref` are not authorization to reuse a sample. `brand_ref` and `brand_url` identify the same brand when `brand_url`'s host equals `brand_ref.domain`; only `domain` and `brand_id` are read on talent. +Collection cards reach buyers in-band. Products keep their `{publisher_domain, collection_ids}` selectors, and when the buyer sets `include_collections: true` the `list_products`, `request_proposals` and `refine_proposals` responses can carry a top-level `collections` array with the full object for each referenced collection (see [collections in responses](#collections-in-responses)). Sellers that list `media_buy.collection_catalog` also serve the same cards outside a brief through [`list_collections`](/docs/media-buy/task-reference/list_collections), by key or with filters, and push card changes to buyer mirrors through [collection card webhooks](/docs/media-buy/task-reference/list_collections#collection-card-webhooks). For a creator marketplace or a large podcast network this replaces fetching every publisher's `adagents.json` to draw one proposal, and it keeps fast-moving facts such as samples current. Sellers can also attach samples to the product card with the `sample_content` [reference asset role](/docs/media-buy/product-discovery/media-products#reference-assets), as a `url` asset built from `post_url` (the role cannot carry `platform`, `published_at` or `identity_ref`). Consumers skip `sample_content` entries without `post_url`, and `reference_authorization` and `identity_ref` are not authorization to reuse a sample. `brand_ref` and `brand_url` identify the same brand when `brand_url`'s host equals `brand_ref.domain`; only `domain` and `brand_id` are read on talent. Each fact has one home: @@ -853,15 +853,15 @@ Products reference collections via `collections` selectors — the same pattern ### Collections in responses -`get_products`, [`list_products`](/docs/media-buy/task-reference/list_products), [`request_proposals`](/docs/media-buy/task-reference/request_proposals) and [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals) responses can carry a top-level `collections` array (experimental, `media_buy.collection_cards`). Each entry is a full collection object with `publisher_domain` required, because `collection_id` is unique only within its publisher. +[`list_products`](/docs/media-buy/task-reference/list_products), [`request_proposals`](/docs/media-buy/task-reference/request_proposals) and [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals) responses can carry a top-level `collections` array (experimental, `media_buy.collection_cards`). The 3.3 betas also carried it, and `include_collections`, on the deprecated `get_products`; they are withdrawn from it ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)), and a `get_products` buyer resolves collections from `adagents.json`. Each entry is a full collection object with `publisher_domain` required, because `collection_id` is unique only within its publisher. -- **Opt-in.** Each of those requests takes an optional `include_collections` boolean, default `false`. Sellers MUST NOT return `collections` unless the request set `include_collections: true`, so buyers that only need selectors never pay for the objects. The `get_products` request accepts unknown fields, so a seller without the feature ignores the flag there. The other three requests reject unknown fields, so buyers send the flag only to sellers that list `media_buy.collection_cards` in `experimental_features`. +- **Opt-in.** Each of those requests takes an optional `include_collections` boolean, default `false`. Sellers MUST NOT return `collections` unless the request set `include_collections: true`, so buyers that only need selectors never pay for the objects. Schemas before 3.2.8 close these requests and reject unknown fields, so buyers send the flag only to sellers that list `media_buy.collection_cards` in `experimental_features`. - **Scope.** Entries cover collections referenced by a returned product's `collections` selectors, keyed by `(publisher_domain, collection_id)`. Sellers MUST NOT include a collection that no returned product references. On a paginated read, that means products on the current page. The array appears only alongside `products`, never on a rejected or `unchanged` response, and a `fields` projection that omits product `collections` omits it too. - **Completeness.** When `include_collections` is `true`, sellers SHOULD include every referenced collection. Omission is allowed, for example for a very large bundle. Buyers detect omissions by comparing the products' selectors with the array, and resolve a missing collection from the publisher's `adagents.json`, as before. - **Duplicates and strays.** If a key appears more than once, that collection is unresolvable from the response, and buyers fall back to `adagents.json` for it. Buyers ignore entries that no returned product references. - **Authority.** The response entry is a convenience copy from the selling agent. The publisher's `adagents.json` remains the root of authorization: which agent may sell which collection is answered only by its `authorized_agents` entries, including [collection-scoped selectors](/docs/governance/property/adagents#collections). A response copy MUST NOT be treated as authorization evidence. When the copy and `adagents.json` disagree, the copy wins only on `images`, `sample_content`, `url`, `description`, `season`, `cadence` and `distribution[].followers`. Every other field, including `status`, `talent`, `content_rating`, `genre`, `kind`, `special` and the rest of `distribution`, stays anchored to `adagents.json`. A copy that omits one of the closed-list fields leaves the declared value. A copy's `followers` apply to the declared `distribution` entry with the same `publisher_domain` (or, when several declared entries share it, the one with the same identifiers); copy entries the publisher does not declare are ignored. `season` and `cadence` are on the list because they go stale between updates to the publisher's file and drive neither suitability nor pricing. Facts buyers use for suitability or pricing, such as `content_rating`, `genre` and `production_quality`, stay with the publisher so that a reseller cannot restate them. [Definition pins](/docs/media-buy/specification#definition-pins) hash the `adagents.json` declaration, never the response copy. - **Unverified copies.** An entry whose `(publisher_domain, collection_id)` is not declared in that publisher's `adagents.json`, or that comes from a selling agent that `adagents.json` does not authorize for the collection, is unverified display data. It does not establish that the collection exists or is sellable, and buyers MUST NOT present it as the publisher's declaration. A response copy's `distribution` MUST NOT feed the carriage [verification states](#verification-states), which read `distribution[]` only from the owner's own file. -- **Feed versions.** `include_collections` is part of the version scope of the `get_products` `wholesale_feed_version` and the `list_products` `feed_version`, for both `public` and `account` `cache_scope`. Absent and `false` are the same scope. Without the flag, collection copies are outside the version, so a card change alone never makes a buyer that did not ask for cards refetch the feed. With `include_collections: true`, the version also changes whenever any collection copy those reads would return changes, so an `unchanged` response never hides a fresher copy. A token issued under one setting and presented with the other is a mismatch, and the seller returns the full payload, as for any other scope-key difference. Sellers MUST issue distinct tokens for the two settings so the mismatch is detectable. [Wholesale feed webhooks](/docs/media-buy/task-reference/list_products#wholesale-feed-webhooks) for products carry no collections, and their versions belong to the scope without the flag. A webhook-fed mirror keeps cards current through the [`collection_card.*` and `collection_catalog.bulk_change` events](/docs/media-buy/task-reference/list_collections#collection-card-webhooks) (experimental, `media_buy.collection_catalog`), which carry their own `list_collections` version. Against a seller without them, it refreshes cards through a full read with `include_collections: true`. +- **Feed versions.** `include_collections` is part of the version scope of the `list_products` `feed_version`, for both `public` and `account` `cache_scope`. Absent and `false` are the same scope. Without the flag, collection copies are outside the version, so a card change alone never makes a buyer that did not ask for cards refetch the feed. With `include_collections: true`, the version also changes whenever any collection copy those reads would return changes, so an `unchanged` response never hides a fresher copy. A token issued under one setting and presented with the other is a mismatch, and the seller returns the full payload, as for any other scope-key difference. Sellers MUST issue distinct tokens for the two settings so the mismatch is detectable. [Wholesale feed webhooks](/docs/media-buy/task-reference/list_products#wholesale-feed-webhooks) for products carry no collections, and their versions belong to the scope without the flag. A webhook-fed mirror keeps cards current through the [`collection_card.*` and `collection_catalog.bulk_change` events](/docs/media-buy/task-reference/list_collections#collection-card-webhooks) (experimental, `media_buy.collection_catalog`), which carry their own `list_collections` version. Against a seller without them, it refreshes cards through a full read with `include_collections: true`. Selectors on products are unchanged, so a buyer that ignores `collections` keeps working. @@ -1126,7 +1126,7 @@ Buyers discover collections through the standard `get_products` workflow. Natura } ``` -The seller returns products with `collections` selectors and, when the request set `include_collections: true`, may include the full objects in the response's top-level [`collections`](#collections-in-responses) array. A seller that lists `media_buy.collection_catalog` also lets buyers browse or look up its cards directly with [`list_collections`](/docs/media-buy/task-reference/list_collections). The buyer resolves any others from each publisher's [adagents.json](/docs/governance/property/adagents). Registry clients can also bootstrap and look up the crawled collection catalog through `/api/registry/catalog/collections/sync` and `/api/registry/catalog/collections/distribution`, which is useful for cross-referencing platform aliases such as YouTube channel IDs back to the publisher-declared collection. +The seller returns products with `collections` selectors. `get_products` does not return the full objects; [`list_products`](/docs/media-buy/task-reference/list_products), [`request_proposals`](/docs/media-buy/task-reference/request_proposals) and [`refine_proposals`](/docs/media-buy/task-reference/refine_proposals) can, in the response's top-level [`collections`](#collections-in-responses) array, when the request sets `include_collections: true`. A seller that lists `media_buy.collection_catalog` also lets buyers browse or look up its cards directly with [`list_collections`](/docs/media-buy/task-reference/list_collections). The buyer resolves any others from each publisher's [adagents.json](/docs/governance/property/adagents). Registry clients can also bootstrap and look up the crawled collection catalog through `/api/registry/catalog/collections/sync` and `/api/registry/catalog/collections/distribution`, which is useful for cross-referencing platform aliases such as YouTube channel IDs back to the publisher-declared collection. For community-maintained entries, registry moderators can seed a publisher-scoped collection with `PUT /api/registry/catalog/collections/{publisher_domain}/{collection_id}`. This creates a contributed registry record and emits the same `collection.created` / `collection.updated` feed events. It does not replace publisher-origin proof: once the publisher declares the collection in their own `adagents.json`, the authoritative declaration wins. diff --git a/docs/media-buy/product-discovery/media-products.mdx b/docs/media-buy/product-discovery/media-products.mdx index fff9567ca65..07b90b8b559 100644 --- a/docs/media-buy/product-discovery/media-products.mdx +++ b/docs/media-buy/product-discovery/media-products.mdx @@ -30,7 +30,7 @@ Products declare which pricing models they support. Buyers select a specific pri - `installments` (list[Installment], optional): Specific installments available within this product. The canonical Product that the compact lifecycle reads carries the same field with a different, closed item shape — `CanonicalInstallment`, which requires `collection_ref` and drops the deprecated `collection_id` shorthand. See [Collections and installments](/docs/media-buy/product-discovery/collections-and-installments#installments-in-the-compact-lifecycle). - `delivery_type` (string, required): Either `"guaranteed"` or `"non_guaranteed"`. - `exclusivity` (string, optional): Whether this product offers exclusive access. `"none"` (default when absent) — multiple advertisers can buy simultaneously. `"category"` — one advertiser per industry category. `"exclusive"` — sole sponsorship. Most relevant for guaranteed products tied to specific shows or placements. -- `pricing_options` (list[PricingOption], required): Array of available pricing models for this product. A binding option applies uniformly across later values permitted by `overlay_support`, except for [`price_adjustments`](/docs/media-buy/advanced-topics/pricing-models#selection-dependent-price-adjustments) the option itself declares; a changed fixed price, floor, currency, model, or priced applicability receives a new `pricing_option_id`. Sellers with value-dependent rates use concretely targeted configured products, separate rate-tier products, or non-binding guidance. See [Pricing Models](#pricing-models). +- `pricing_options` (list[PricingOption], required): Array of available pricing models for this product. A binding option applies uniformly across later values permitted by `overlay_support`; a changed fixed price, floor, currency, model, or priced applicability receives a new `pricing_option_id`. Sellers with value-dependent rates use concretely targeted configured products, separate rate-tier products, or non-binding guidance. See [Pricing Models](#pricing-models). - `delivery_measurement` (object, optional): Who measures ad delivery — the ad server and viewability vendor used to count impressions. New implementations populate `vendors` as a structured `BrandRef` array (e.g., `[{ "domain": "googleadmanager.com" }, { "domain": "integralads.com" }]`); the legacy `provider` string is deprecated. When absent, buyers should apply their own measurement defaults. See [Delivery Measurement](#delivery-measurement). - `outcome_measurement` (OutcomeMeasurement, **deprecated**): Legacy field for declaring business outcome measurement (lift, brand lift, foot traffic). New implementations declare outcome metrics via `reporting_capabilities.available_metrics` and pin attribution methodology + window via the `qualifier` slot on `committed_metrics`. Retained for one-minor backwards compatibility; removed at the next major. See [Commerce Media](/docs/media-buy/commerce-media) for the migration pattern. - `creative_policy` (CreativePolicy, optional): Creative requirements and restrictions, including the optional product-scoped `review_sla` for time to an approved or rejected decision. See [Service commitments](/docs/media-buy/service-commitments) for business calendars and critical-report SLAs. @@ -38,7 +38,7 @@ Products declare which pricing models they support. Buyers select a specific pri - `expires_at` (datetime, conditionally required): Required for a request-specific product issued through targeting-aware discovery and whenever `targeting_resolution` is present. Earlier custom products remain schema-valid when it is absent. After this time, a recognized expired ID issued to the authenticated account and lineage returns `PRODUCT_EXPIRED`; an ID whose tombstone is no longer retained or belongs to another account/lineage returns `PRODUCT_NOT_FOUND`, preventing cross-tenant existence disclosure. - `overlay_support` (TargetingOverlaySupport, optional): Product-scoped targeting dimensions whose values may be selected later. Required when requested through `required_overlay_support`. It guarantees selectable capability subject to disclosed limits, not inventory or a forecast for every value. - `identity` (object, optional, experimental): Product-scoped persistent-identifier and custom-reach-methodology facts. A product declaring `persistent_identifier: false` omits `overlay_support.frequency_cap` and `overlay_support.frequency_cap_support`; `devices`, `accounts`, and `cookies` are not valid delivery reach units for it, while modeled `individuals` and `households` remain valid. Its frequency-only delivery rows carry `reach_unit`; a custom unit reported with either reach or frequency requires `identity.reach_methodology`. Sellers using this surface list `media_buy.product_identity` in `experimental_features`; see [Product identity absence and reach reporting](/docs/media-buy/specification#product-identity-absence-and-reach-reporting-experimental). Optional `identity.match_keys` lists the identifiers the product resolves, with scopes and uses, and is authoritative over the seller-wide `supported_match_keys`; sellers using it also list `media_buy.match_keys`. See [Match keys and cross-publisher frequency capping](/docs/media-buy/specification#match-keys-and-cross-publisher-frequency-capping-experimental). -- `execution_requirements` (list[ProductExecutionRequirement], optional, experimental): Account resources a package on this product needs before `create_media_buy` succeeds — an `event_source` bound through `optimization_goals[].event_sources[]`, a `catalog` of one of the listed types bound through `packages[].catalogs[]` (use `"app"` for app promotion), or a `downstream_connection` such as the publisher identity the ads run as. Every entry is required. The declaration is account-independent and does not change `cache_scope`; when present, together with the selected formats' `required_connections`, it is complete for these kinds. Sellers using this surface list `media_buy.execution_requirements` in `experimental_features`; see [Product execution requirements](/docs/media-buy/specification#product-execution-requirements-experimental). +- `execution_requirements` (list[ProductExecutionRequirement], optional, experimental): Account resources a purchase on this product needs before it is bought — an `event_source` bound through `optimization_goals[].event_sources[]`, a `catalog` of one of the listed types bound through `purchases[].catalog_ids[]` on `buy_products` or `packages[].catalogs[]` on the legacy `create_media_buy` (use `"app"` for app promotion), or a `downstream_connection` such as the publisher identity the ads run as. Every entry is required. The declaration is account-independent and does not change `cache_scope`; when present, together with the selected formats' `required_connections`, it is complete for these kinds. Sellers using this surface list `media_buy.execution_requirements` in `experimental_features`; see [Product execution requirements](/docs/media-buy/specification#product-execution-requirements-experimental). - `hold_policy` (HoldPolicy, optional, experimental): Whether finalizing a proposal that allocates this product places an inventory hold (`available`) and, if so, the promised `min_duration`, the longest initial `max_duration`, whether the hold is `extendable`, `max_total_duration`, and whether the hold may be `rankable` behind other buyers' holds (`media_buy.hold_ranking`). It is a planning hint for buyers before requesting a proposal: it binds nothing, reserves nothing, and does not guarantee availability. Only a draft proposal's `hold_policy` binds; a draft allocating any product with `available: false` declares `available: false` and finalizes terms only. When absent, the agent-level `hold_semantics` default applies. Sellers using this surface list `media_buy.hold_policy` in `experimental_features`; see [Hold policy](/docs/media-buy/task-reference/refine_proposals#hold-policy-experimental). - `targeting_resolution` (ProductTargetingResolution, optional): Sparse differences from a structured overlay. Absence confirms exact acceptance of that product's structured overlay, but not how prose was interpreted; response-level `targeting_resolution.brief_targeting` confirms hard brief interpretation once for the result set when that interpretation materially affects eligibility, pricing, or forecasting. Presence requires `is_custom: true` and `expires_at`. - `list_applications` (list[InventoryListApplication], conditionally required): One product-scoped receipt for every effective property- or collection-list targeting reference, regardless of field projection. Exclusion applications receive a receipt even when they match zero entries; zero matches for any inclusion application make the product ineligible, so it is not returned. Each receipt identifies the list without echoing separately supplied fetch credentials, records `resolved_at` and `evaluated_at`, and partitions the resolved snapshot into `summary.matched` and `summary.unmatched`. Counts apply to this product only; pricing and forecasts reflect the eligible inventory after all effective lists are composed. @@ -197,8 +197,6 @@ The three concepts remain separate: When a buyer supplies evidence requirements and evidence affects product inclusion or rank, the returned Product carries `audience_evidence_selections[]` with the exact matching snapshots and `decision_use` of `eligibility` or `recommendation`. This decision readback is mandatory even when the buyer's `fields` projection omitted `audience_evidence_selections`; projection may omit the optional full evidence payload, not the explanation of an applied policy. -Buyers can also name the audiences they want evidence for with the experimental `target_audiences[]`, a sibling of `audience_evidence_requirements` on `get_products` filters ([`get_products`](/docs/media-buy/task-reference/get_products#target-audiences-experimental), `media_buy.audience_evidence_targets`). A target is satisfied only by admissible evidence for exactly that audience, ranks or excludes products by `requirement_mode`, and is never a targeting predicate. - At buy time, a package can repeat `audience_evidence_requirements` (and, experimentally, the sibling `target_audiences`) and can carry `audience_evidence_pins[]` copied from discovery. Every pin includes `evidence_id`, `snapshot_id`, `version`, and `content_digest`; the seller rejects a missing or mutated snapshot instead of substituting current catalog content. The confirmed Package returns a matching `audience_evidence_selections[]` entry with `decision_use: "package_construction"` for every accepted pin and every snapshot used to satisfy package requirements, and preserves that readback on later package reads. When an attestation affected either decision, readback preserves the exact reference and its `AttestationEvaluation` as one pair. That pair is valid only when the reference is published on the selected snapshot, its claim and issuer satisfy both buyer and seller policy, `reference_digest` covers that same reference, the outcome is `verified`, and both the subject digest and action-binding digest equal the evidence `content_digest`. An evaluation for one reference cannot verify a different reference. Sellers retain the full immutable snapshot and evaluations for at least as long as the package remains readable. Buyers should cache the evidence returned during discovery; AdCP 3.2 does not introduce a buyer-controlled snapshot fetch URL. Sellers may embed the full snapshot in readback, but need not duplicate it on every product or package. diff --git a/docs/media-buy/product-discovery/refinement.mdx b/docs/media-buy/product-discovery/refinement.mdx index 2b7c293b995..d9e24143a55 100644 --- a/docs/media-buy/product-discovery/refinement.mdx +++ b/docs/media-buy/product-discovery/refinement.mdx @@ -66,146 +66,18 @@ Product-scoped entries may declare an action. When omitted, the seller treats th } ``` -### Check an exact package before booking - -In AdCP 3.3, a product entry with `action: "include"` (or no action) may -carry an optional `package`. This asks whether the exact proposed package -fits, using the same field types and validation rules as a package on -`create_media_buy`. The enclosing entry supplies `product_id`; omit it inside -`package`. `pricing_option_id` and numeric `budget` are required. - -```json -{ - "$schema": "https://adcontextprotocol.org/schemas/v3/media-buy/get-products-request.json", - "adcp_version": "3.3", - "adcp_major_version": 3, - "buying_mode": "refine", - "refine": [ - { - "scope": "product", - "product_id": "prod_homepage_takeover", - "action": "include", - "package": { - "pricing_option_id": "cpm_guaranteed", - "budget": 25000, - "start_time": "2026-11-01T00:00:00Z", - "end_time": "2026-11-30T23:59:59Z", - "targeting_overlay": {} - } - } - ] -} -``` - -**Resolve the inputs as on create.** The budget is in the selected pricing -option's currency. An explicit `impressions` goal has the same meaning as on -create; otherwise the seller derives the goal from the budget and selected -pricing terms when possible. For example, a budget of $25,000 at a fixed $10 -CPM implies 2,500,000 impressions. A budget alone need not imply a delivery -goal for flat-rate or auction pricing. If the goal cannot be determined -unambiguously, the seller reports `unable` rather than inventing a goal. - -Explicit package `start_time` and `end_time` take precedence. Each omitted -boundary defaults to the corresponding `filters.start_date` or `end_date`, -using the seller's availability-check date and timezone semantics. If those -inputs cannot resolve an exact flight, the seller reports `unable`; buyers -can supply explicit timestamps to remove ambiguity. An `applied` outcome MUST -echo both exact boundaries as `resolved_start_time` and `resolved_end_time`, -including boundaries supplied explicitly. The end MUST be after the start. -Resolve the product's -bound discovery targeting and any replacement top-level `targeting_overlay` -first, then apply `package.targeting_overlay` per dimension as on create: -omission inherits, non-null values replace, and `null` clears a configurable -default. An empty object inherits targeting; it does not request untargeted -inventory. Inherent product scope and offer filters remain binding. Free-text -`ask` cannot override structured package inputs; contradictory requirements -are rejected with `INVALID_REQUEST`. - -**Return an exact result or explain why it cannot be computed.** A seller -handling a request containing any `package` MUST return the full, -position-matched `refinement_applied` array. For each such entry: - -- `applied` means the returned product carries a `forecast` computed for - exactly the resolved package goal, flight, targeting, and other supplied - controls. The outcome MUST include `result_product_id`, identifying exactly - one returned Product, and both resolved flight timestamps. The outcome's - `product_id` still echoes the request. Sellers MUST return this forecast even - when `fields` omitted it. - It uses `forecast_range_unit: "availability"`; points omit `budget`, report - total available units in the goal metric in `metrics`, and carry - `availability_status`. Zero availability still reports the goal metric as - zero so the buyer can calculate the shortfall. -- `unable` with non-empty `notes` explains unsupported controls, an - unresolvable goal or flight, or an unavailable forecasting service. The - corresponding product MUST NOT carry a forecast computed for different - inputs. Sellers MUST NOT silently drop a control, substitute dates or - targeting, or label a package forecast `partial`. - -Insufficient inventory is a successfully computed (`applied`) forecast with -`availability_status: "unavailable"`, rather than a failure to forecast. With -2,000,000 available impressions in the CPM example, the shortfall is 500,000. -Do not cap available units at the goal: the metrics report total availability. -Forecast method describes the calculation, so a read-only check normally uses -`estimate` or `modeled`; it does not establish reserved, guaranteed delivery. - -**Carry the exact configuration into purchase.** Changed request-bound -targeting or forecast assumptions require a distinguishable configured -`product_id`, as in ordinary refinement. Use `result_product_id` to find that -product; product-array order is not a correlation mechanism. The returned -product MUST retain the requested `pricing_option_id` and identical pricing -terms. If the seller needs to substitute or reprice the option, it reports -`unable` rather than computing a different budget-to-goal relationship. - -The seller binds effective discovery/top-level targeting to the returned ID -and evaluates the package overlay with create's inheritance rules. It MUST -NOT turn package replacements or clears into additional inherent product -scope, or report them as deviations from top-level discovery targeting in -Product `targeting_resolution`. At `create_media_buy`, the buyer uses the -mapped ID and unchanged package controls, including the same targeting -overlay, budget, and pricing option, and materializes both resolved timestamps -on the package. The media-buy flight must encompass those timestamps. Changing -any forecast input requires a fresh check. - -For example, an entry for `prod_homepage_takeover` with omitted package times -and date filters may produce this outcome after resolving the seller's local -date boundaries: - -```json -{ - "scope": "product", - "product_id": "prod_homepage_takeover", - "result_product_id": "prod_homepage_takeover_configured", - "resolved_start_time": "2026-11-01T00:00:00-05:00", - "resolved_end_time": "2026-11-30T23:59:59-05:00", - "status": "applied" -} -``` - -The buyer sets the create package's `product_id` to -`prod_homepage_takeover_configured`, and `start_time`/`end_time` to those exact -timestamps. If its forecast package carried `geo_countries: null`, it repeats -that clear in `targeting_overlay`; it does not restore the old product's -country default. - -**Each entry is an independent read.** Sellers MUST forecast each package -against current inventory without subtracting the other proposed packages in -the call. Products sharing inventory can therefore each report that inventory; -buyers MUST NOT sum their forecasts as a jointly bookable plan. The existing -one-entry-per-product rule still applies; compare two configurations of the -same product in separate calls. The check MUST NOT create a media buy, book, -hold, or reserve inventory, or upload or assign creatives carried in the -package. Finalizing a proposal remains the inventory-hold operation. A later -purchase still checks availability and can fail with `PRODUCT_UNAVAILABLE`. - -There is no separate structured-package capability flag. Buyers MUST -negotiate AdCP 3.3 or later before treating an `applied` outcome as exact-package -confirmation; a legacy seller may ignore an unfamiliar input. Check the served -`adcp_version` echo: a downshift or missing echo does not confirm 3.3 support. An `applied` -outcome is evidence for this entry only. Missing `refinement_applied`, a missing -matching outcome, or a legacy seller rejecting the new field is no evidence -that the exact package was forecast; buyers MUST NOT treat an ordinary product -forecast as confirmation. Entries without `package` retain their existing -behavior, including optional per-entry outcomes. +### Exact package forecasts (withdrawn) + +The 3.3 betas let a product entry carry an exact `package` for a read-only +availability forecast, answered with `result_product_id`, +`resolved_start_time` and `resolved_end_time` on its `refinement_applied` +entry. That surface is withdrawn from this deprecated task before 3.3 GA +([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)): 3.3 adds +no field that exists only on a deprecated task, and every `refine[]` entry +rejects `package`. Where an exact-package forecast belongs on the compact +lifecycle is an open working-group question. Until it is settled, check +availability with `forecast` and concrete `targeting_overlay` values, and treat +the buy as the authoritative availability check. ### Request-level direction @@ -274,11 +146,9 @@ When a buyer sends a `refine` array, the seller responds with `refinement_applie |-------|------|----------|-------------| | `scope` | string | Yes | Echoes the scope (`"request"` / `"product"` / `"proposal"`) from the corresponding `refine` entry. | | `product_id` | string | Yes when `scope` is `"product"` | Echoes `product_id` from the corresponding refine entry. | -| `result_product_id` | string | For an applied package forecast | Identifies exactly one returned Product carrying the exact forecast; may differ from the echoed request ID. | -| `resolved_start_time`, `resolved_end_time` | date-time | With `result_product_id` | Exact forecast flight boundaries, copied to the package at create. | | `proposal_id` | string | Yes when `scope` is `"proposal"` | Echoes `proposal_id` from the corresponding refine entry. | | `status` | string | Yes | `"applied"`: ask fulfilled. `"partial"`: partially fulfilled. `"unable"`: could not fulfill. | -| `notes` | string | Conditional | Seller explanation. Recommended when status is `"partial"` or `"unable"`; required and non-empty for a structured package entry with status `"unable"`. | +| `notes` | string | No | Seller explanation. Recommended when status is `"partial"` or `"unable"`. | ```json { @@ -295,7 +165,7 @@ When a buyer sends a `refine` array, the seller responds with `refinement_applie } ``` -The `refinement_applied` array MUST contain the same number of entries in the same order as the `refine` array. Each entry MUST echo `scope` and the matching id (`product_id` on product scope, `proposal_id` on proposal scope) so orchestrators can cross-validate alignment. The field is optional unless any entry carries `package`, in which case the seller MUST return it for the entire request. Sellers that return it MUST return valid, position-matched entries. +The `refinement_applied` array MUST contain the same number of entries in the same order as the `refine` array. Each entry MUST echo `scope` and the matching id (`product_id` on product scope, `proposal_id` on proposal scope) so orchestrators can cross-validate alignment. The field is optional, but sellers that return it MUST return valid, position-matched entries. Orchestrators SHOULD cross-check entries by the echoed id rather than trusting positional order alone — a seller bug that reorders entries would otherwise silently mis-attribute each outcome. @@ -322,7 +192,7 @@ Buyers discover this legacy refinement mode when `get_adcp_capabilities.media_bu When the seller returns `refinement_applied`, read the matching entry's `status` (`applied`, `partial`, or `unable`) and optional `notes` to learn how it handled this specific request. These fields acknowledge handling; they are not the executable commercial terms. Inspect the returned proposal's pricing and allocations before finalizing or buying. -For requests without structured `package` entries, the entire `refinement_applied` field is optional; omission communicates no per-ask outcome: do not infer `applied`, `partial`, or `unable`. A seller may omit it even when the response applies the requested change. Treat the returned proposal and any reported outcome as runtime evidence for this request, not as a general promise that the seller can negotiate price. +Because the entire `refinement_applied` field is optional, omission communicates no per-ask outcome: do not infer `applied`, `partial`, or `unable`. A seller may omit it even when the response applies the requested change. Treat the returned proposal and any reported outcome as runtime evidence for this request, not as a general promise that the seller can negotiate price. ### Find similar products @@ -500,7 +370,6 @@ The [Media Buy Specification](/docs/media-buy/specification#get_products) define - MUST provide `scope` and `product_id` for each product entry, and `scope` and `proposal_id` for each proposal entry - MAY omit `action` on product and proposal entries — sellers treat missing `action` as `"include"` - MUST NOT include multiple entries for the same product ID or proposal ID in a single `refine` array -- MUST use `include` (or omit `action`) when supplying a structured `package`; `package` is invalid on other scopes or product actions **Sales agents:** - MUST omit products with `action: "omit"` from the response @@ -511,7 +380,6 @@ The [Media Buy Specification](/docs/media-buy/specification#get_products) define - SHOULD consider request-level asks when composing the response — this MAY result in additional products beyond those explicitly referenced. Per-product actions take precedence over request-level direction. - SHOULD fulfill the `ask` on proposal entries with `action: "include"` - SHOULD include `refinement_applied` in the response when the buyer provides `refine`, with one entry per change request matched by position -- MUST follow the [exact-package forecast contract](#check-an-exact-package-before-booking) when a product entry carries `package`, including mandatory outcomes, exact inputs, independent availability forecasts, and no booking or inventory hold - MAY return proposals even when the buyer did not include proposal entries ## See also diff --git a/docs/media-buy/specification.mdx b/docs/media-buy/specification.mdx index be90eef3a42..1767c4966b2 100644 --- a/docs/media-buy/specification.mdx +++ b/docs/media-buy/specification.mdx @@ -111,9 +111,8 @@ boolean and array subset. Unrequested fields and numeric seller limits do not participate. Forecasts without concrete values describe the product's discovery/default scope; buyers rediscover with concrete `targeting_overlay` values for value-specific forecasts. Fixed prices and floors remain binding -uniformly for supported selections, except for adjustments the selected fixed-price -option declares in `price_adjustments`; price guidance remains non-binding. -Sellers with other value-dependent rates return a concretely targeted configured +uniformly for supported selections, while price guidance remains non-binding. +Sellers with value-dependent rates return a concretely targeted configured product, split rate tiers into products, or withhold binding prices until concrete rediscovery; they never reuse a selected `pricing_option_id` at new terms. @@ -279,8 +278,9 @@ Many products need account resources that live outside the media buy: a conversion product needs a pixel or dataset, an app-promotion product needs a registered app, a catalog-sales product needs a product catalog, and a product that runs as a page or profile needs that identity connected. -`Product.execution_requirements` lists these needs so a buyer knows, before -`create_media_buy`, what it must supply and where it goes on the request. A +`Product.execution_requirements` lists these needs so a buyer knows, before it +buys (`buy_products`, or the legacy `create_media_buy`), what it must supply and +where it goes on the request. A seller using this experimental surface lists `media_buy.execution_requirements` in `experimental_features` on `get_adcp_capabilities`. @@ -288,8 +288,8 @@ Each entry's `kind` determines where the resource is bound: | `kind` | Satisfied by | Established through | |---|---|---| -| `event_source` | A package `optimization_goals[]` entry of `kind: "event"` that the seller will use (within `max_optimization_goals`, by priority) with a used `event_sources[]` entry (only the first one when the seller does not support `multi_source_event_dedup`) whose `event_source_id` names an event source available to the account and whose `event_type` is in `event_types` when that list is present | [`sync_event_sources`](/docs/media-buy/task-reference/sync_event_sources). When `conversion_tracking.platform_managed` is `true`, the seller-managed source's ID is the `sync_event_sources` response entry with `managed_by: "seller"` | -| `catalog` | A `packages[].catalogs[]` entry whose `type` is in `catalog_types` | [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs), an inline catalog, or a selector (`ids`, `gtins`) over the seller's own catalog | +| `event_source` | A purchase or package `optimization_goals[]` entry (`purchases[].optimization_goals[]` on `buy_products`; `packages[].optimization_goals[]` on the legacy `create_media_buy`) of `kind: "event"` that the seller will use (within `max_optimization_goals`, by priority) with a used `event_sources[]` entry (only the first one when the seller does not support `multi_source_event_dedup`) whose `event_source_id` names an event source available to the account and whose `event_type` is in `event_types` when that list is present | [`sync_event_sources`](/docs/media-buy/task-reference/sync_event_sources). When `conversion_tracking.platform_managed` is `true`, the seller-managed source's ID is the `sync_event_sources` response entry with `managed_by: "seller"` | +| `catalog` | On `buy_products`, a `purchases[].catalog_ids[]` entry naming a synced catalog whose `type` is in `catalog_types`. On the legacy `create_media_buy`, a `packages[].catalogs[]` entry whose `type` is in `catalog_types` | [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs). The legacy package form also accepts an inline catalog or a selector (`ids`, `gtins`) over the seller's own catalog | | `downstream_connection` | A completed seller-side connection or grant of the declared `connection.connection_type` — not a request field | The seller's connection flow, as described for `AUTHORIZATION_REQUIRED` | ```json @@ -384,14 +384,22 @@ seller using this experimental surface lists `media_buy.execution_readiness` in `experimental_features` on `get_adcp_capabilities`, and also lists `media_buy.execution_requirements`. -A buyer sets `include_execution_readiness: true` on `get_products` together with -an `account`. A seller that supports it returns a response-level -`execution_readiness` map keyed by `product_id`: +A buyer sets `include_execution_readiness: true` on +[`list_products`](/docs/media-buy/task-reference/list_products#per-account-execution-readiness-experimental) +together with an `account`. A seller that supports it returns a response-level +`execution_readiness` map keyed by `product_id`. The 3.3 betas carried the map +on the deprecated `get_products`; it moved to `list_products` before 3.3 GA +([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). Because +the next step from `list_products` is `buy_products`, `binding_field` names the +`buy_products` path: `purchases[].optimization_goals[].event_sources[].event_source_id` +for an event source and `purchases[].catalog_ids[]` for a catalog. The +`packages[]` paths of the legacy `create_media_buy` are not used here. ```json { + "outcome": "listed", "cache_scope": "public", - "wholesale_feed_version": "wf_2026_10_06", + "feed_version": "feed_2026_10_06", "execution_readiness": { "version": "er_7f3a", "evaluated_at": "2026-10-06T12:00:00Z", @@ -402,7 +410,7 @@ an `account`. A seller that supports it returns a response-level { "requirement": { "kind": "event_source", "event_types": ["app_install"] }, "readiness_status": "selection_required", - "binding_field": "packages[].optimization_goals[].event_sources[].event_source_id", + "binding_field": "purchases[].optimization_goals[].event_sources[].event_source_id", "candidates": [ { "resource_id": "es_app_main", "name": "Main app SDK" }, { "resource_id": "es_app_beta", "name": "Beta app SDK" } @@ -411,7 +419,7 @@ an `account`. A seller that supports it returns a response-level { "requirement": { "kind": "catalog", "catalog_types": ["app"] }, "readiness_status": "ready", - "binding_field": "packages[].catalogs[]", + "binding_field": "purchases[].catalog_ids[]", "resolved": { "resource_id": "cat_app_1", "name": "Acme app" } }, { @@ -445,7 +453,7 @@ Statuses, per requirement and rolled up per product: | `setup_required` | The account has none, or the connection is `missing`, `pending`, `expired`, or `revoked` | Create or restore it, for example with `sync_event_sources`, `sync_catalogs`, or `connection_state.authorization_url` | | `selection_required` | The account has several suitable resources | Choose one from `candidates[]` and bind it | | `input_required` | The seller cannot discover a suitable resource from the account | Supply one on the request, such as an inline catalog | -| `unknown` | The seller could not read the account's resources | Depends on `unknown_reason`: `permission_denied` needs a human to fix the seller's grant on the account, `platform_unavailable` is worth retrying, `not_evaluated` means refetch fewer products. Meanwhile `create_media_buy` decides | +| `unknown` | The seller could not read the account's resources | Depends on `unknown_reason`: `permission_denied` needs a human to fix the seller's grant on the account, `platform_unavailable` is worth retrying, `not_evaluated` means refetch fewer products. Meanwhile the purchase task decides | Rules: @@ -466,8 +474,8 @@ Rules: that is `unknown`. A seller MAY report products beyond its evaluation budget as `unknown` with `not_evaluated`. - **`ready` does not waive binding.** For `event_source` and `catalog`, the - buyer still passes `resolved.resource_id` in `binding_field`; an unbound - requirement is `not_bound` per + buyer still passes `resolved.resource_id` in `binding_field`; on the legacy + `create_media_buy`, an unbound requirement is `not_bound` per [`execution-requirement-unmet.json`](https://adcontextprotocol.org/schemas/v3/error-details/execution-requirement-unmet.json). `resolved` is required when such a requirement is `ready`. - **Candidates are directly usable.** A `resource_id` MUST be a value the @@ -491,21 +499,23 @@ Rules: `include_execution_readiness: true` and carried an `account` the caller is authorized for; otherwise the seller omits it (an `account` that does not resolve still returns `ACCOUNT_NOT_FOUND`). It covers only the products on the - response. `create_media_buy` still revalidates and rejects per - `execution-requirement-unmet.json` or `AUTHORIZATION_REQUIRED`, which echo the - same requirement. + page. The purchase decides: the legacy `create_media_buy` still revalidates and + rejects per `execution-requirement-unmet.json` or `AUTHORIZATION_REQUIRED`, + which echo the same requirement. A rejection rule for unmet `buy_products` + purchases is not yet specified; it is tracked with proposal bindings in + [adcp#7763](https://github.com/adcontextprotocol/adcp/issues/7763). - **Seller cost.** Whether an account has a pixel, catalog, or connection is the same answer for every product that needs it. Sellers SHOULD read it once per account and requirement kind and stamp every product on the page. **Caching.** The map is not part of the `cache_scope` layer. It does not change -`cache_scope`, `wholesale_feed_version`, or `pricing_version`, so a public +`cache_scope`, `feed_version`, or `pricing_version`, so a public wholesale catalog stays `cache_scope: "public"` when readiness is added. `execution_readiness.version` is an opaque token for the account's readiness, independent of both feed tokens. Buyers MUST NOT dedupe or cache the map under the public key; they key it by `(account, execution_readiness.version)`. Sellers -MUST NOT put it in wholesale feed webhooks. It is omitted on `unchanged: true` -responses, which carry no products, so refreshing readiness means refetching the +MUST NOT put it in wholesale feed webhooks. It is omitted on an `unchanged` +outcome, which carries no products, so refreshing readiness means refetching the page; conditional fetch of the map is not specified. `version` identifies the account's readiness state, not the page: equal versions MUST imply identical entries for any product present in both responses, and buyers merge pages by @@ -1050,7 +1060,6 @@ Each `get_products` request with `buying_mode: "refine"` is self-contained — s - Sales agents SHOULD fulfill the `ask` on proposal entries with `action: "include"` - Sales agents SHOULD include `refinement_applied` in the response, with one entry per change request matched by position - Sales agents that return `refinement_applied` MUST echo `scope` on each entry and MUST echo `product_id` / `proposal_id` for product and proposal scopes, so orchestrators can cross-validate alignment -- In AdCP 3.3, product-scoped `include` entries MAY carry `package` with create-package field types, required `pricing_option_id` and numeric `budget`, and `product_id` supplied by the enclosing entry. Other scopes and actions MUST NOT carry `package`. Sales agents MUST follow the [exact-package forecast contract](/docs/media-buy/product-discovery/refinement#check-an-exact-package-before-booking): resolve the goal, flight, and targeting without guessing; return a complete `refinement_applied` array and either `applied` with an exact availability forecast, `result_product_id` referencing exactly one returned Product with unchanged selected pricing terms, and `resolved_start_time`/`resolved_end_time` to copy to the package at create, or `unable` with non-empty explanatory notes and no substitute forecast; forecast entries independently without subtracting other proposed packages; and perform no booking, hold, reservation, creative upload, or assignment. Insufficient inventory is an `applied` forecast with `availability_status: "unavailable"`. No separate capability flag is defined, and omitted outcomes do not confirm support. - Sales agents MAY return proposals alongside products in refine mode, even when the orchestrator did not include proposal entries ### Canonical creative-format discovery diff --git a/docs/media-buy/task-reference/get_products.mdx b/docs/media-buy/task-reference/get_products.mdx index 73171415f7c..38ae88f69f2 100644 --- a/docs/media-buy/task-reference/get_products.mdx +++ b/docs/media-buy/task-reference/get_products.mdx @@ -197,13 +197,11 @@ asyncio.run(discover_with_filters()) | `media_buy_frequency_cap` | MediaBuyFrequencyCap | No | Exact aggregate max-impression cap intended for the MediaBuy root. Every returned product must support one shared counter for it, so when the value is known this field alone suffices. Legacy `get_products` proposals echo it as `frequency_cap`; compact proposals carry it in `commercial_terms.frequency_cap`. | | `required_overlay_support` | TargetingOverlayRequirements | No | Buyer minimums for targeting dimensions whose values will be supplied on packages later. This requests selectable capability, not current values, value-specific availability or forecasts, and not one product per value. Requirement `true` matches support `true` or any valid support object; an object requirement matches `true` or a containing support object. The daypart exception is that legacy `daypart_targets: true` satisfies only `inventory_local`, not `iana`, requirements. Unrequested fields and numeric seller limits do not participate. Missing or unknown requirements exclude the product. For frequency caps, send `frequency_cap_support` (an empty object requests any support); it also matches legacy `frequency_cap: true`. A requirement carrying both fields is rejected by the schema, because `frequency_cap: true` matches only the broad legacy declaration and would exclude every product that declares constraints. | | `required_media_buy_support` | MediaBuySupportRequirements | No | Product participation required for shared MediaBuy controls when the exact cap is not yet known. `frequency_cap: true` requires aggregate-counter participation; sibling constraints use subset containment after seller-wide inheritance. | -| `include_execution_readiness` | boolean | No | (Experimental, `media_buy.execution_readiness`) With `account`, asks the seller to return the response-level [`execution_readiness`](#execution_readiness-experimental) map. Opt-in because computing it can need reads on the seller's platform. Ignored without `account`. Default `false`. | | `fields` | string[] | No | Specific product fields to include for lightweight discovery. `product_id` and `name` are always included; request `identity` to receive the experimental product-scoped identity declaration, and `execution_requirements` to receive the experimental resources a package needs before creation. Request `audience_evidence` for the full evidence payload. Projection never suppresses required decision readback: modified products include `targeting_resolution` and `expires_at`; a request with `required_overlay_support` receives `overlay_support`; and when an audience-evidence policy affects inclusion or ranking, the seller returns `audience_evidence_selections`. When requesting signal metadata, buyers SHOULD request `included_signals` for bundled/planned signals and the `signal_targeting_*` fields for package-level selection. A request with `required_media_buy_support` or `media_buy_frequency_cap` receives `media_buy_support`. | | `property_list` | PropertyListRef | No | Deprecated discovery-only property filter. Use `targeting_overlay.property_list` for a concrete delivery constraint or `required_overlay_support.property_list` when the list will be selected later. | | `pagination` | PaginationRequest | No | Cursor-based pagination to cap returned `products[]` in curated/refined responses or walk wholesale product feeds (see below) | -| `if_wholesale_feed_version` | string | No | Opaque `wholesale_feed_version` token from a prior wholesale-mode `get_products` response from this agent. Only valid with `buying_mode: "wholesale"`. Version scope excludes `pagination.cursor`: `public` is keyed by (agent, `buying_mode`, `filters`, `targeting_overlay`, `media_buy_frequency_cap`, `required_overlay_support`, `required_media_buy_support`, deprecated `property_list`, `catalog`, `include_collections`); `account` adds account identity. See [Wholesale feed versioning](#wholesale-feed-versioning). | +| `if_wholesale_feed_version` | string | No | Opaque `wholesale_feed_version` token from a prior wholesale-mode `get_products` response from this agent. Only valid with `buying_mode: "wholesale"`. Version scope excludes `pagination.cursor`: `public` is keyed by (agent, `buying_mode`, `filters`, `targeting_overlay`, `media_buy_frequency_cap`, `required_overlay_support`, `required_media_buy_support`, deprecated `property_list`, `catalog`); `account` adds account identity. See [Wholesale feed versioning](#wholesale-feed-versioning). | | `if_pricing_version` | string | No | Opaque `pricing_version` token from a prior response. MUST only be sent together with `if_wholesale_feed_version`. Evaluation order: `if_wholesale_feed_version` mismatch → full payload; `if_wholesale_feed_version` matches but `if_pricing_version` mismatches → full payload (so the buyer sees updated `pricing_options`); both match → seller MAY return `unchanged: true`. Sellers that don't track pricing separately ignore this. | -| `include_collections` | boolean | No | Experimental (`media_buy.collection_cards`), default `false`. When `true`, asks for the response-level `collections` array with the full object for each collection the returned products reference. Sellers MUST NOT return `collections` otherwise. Part of the `wholesale_feed_version` scope (see [Wholesale feed versioning](#wholesale-feed-versioning)). A seller without the feature ignores the flag (this request accepts unknown fields), so compare product selectors with the array to find omissions. See [Collections in responses](/docs/media-buy/product-discovery/collections-and-installments#collections-in-responses). | | `time_budget` | Duration | No | Maximum time the buyer will commit to this request. The seller returns the best results achievable within this budget and does not start processes (human approvals, expensive external queries) that cannot complete in time. When omitted, the seller decides timing. Example: `{"interval": 30, "unit": "seconds"}`. | | `push_notification_config` | PushNotificationConfig | No | Optional webhook channel for async terminal completion/failure notifications on `brief` / `refine` curated discovery. `submitted` responses with a `task_id` remain pollable through [`get_task_status`](https://adcontextprotocol.org/schemas/v3/protocol/get-task-status-request.json) (legacy `tasks/get`) whether or not this field is present. If the request includes this field and the seller returns `submitted`, the seller MUST deliver at least the terminal completion/failure notification to the configured webhook; intermediate progress notifications are MAY. If the seller cannot honor the webhook channel, it MUST reject the request with a structured error instead of silently accepting. Ignored for `wholesale`; sellers MUST NOT route wholesale reads through the Submitted arm because this field is present. | @@ -351,9 +349,8 @@ it does not guarantee inventory or forecast every possible value. Forecasts returned when only future support was requested describe the product's discovery/default scope. Rediscover with concrete `targeting_overlay` values for a value-specific forecast. Fixed prices and floors remain binding uniformly -for supported selections, except for adjustments the selected fixed-price option -declares in `price_adjustments`; price guidance remains non-binding. Sellers with -other value-dependent rates must return a concretely targeted configured product, +for supported selections; price guidance remains non-binding. Sellers with +value-dependent rates must return a concretely targeted configured product, split the rate tiers into products, or withhold binding pricing until concrete rediscovery. They cannot reinterpret a selected `pricing_option_id` at a new price. If a supported selection has no current inventory, creation returns @@ -446,7 +443,7 @@ targeting filter and the legacy top-level `property_list`. | `required_performance_standards` | [PerformanceStandard[]](/docs/media-buy/advanced-topics/pricing-models#measurement-terms-and-performance-standards) | Filter to products that can meet the buyer's performance standard requirements. Each entry specifies a metric, threshold, and vendor (e.g., "DoubleVerify for viewability at 70% MRC"). Products that cannot meet these thresholds or do not support the specified vendors are excluded. An entry may add `metric_id` to name which of the vendor's metrics the threshold applies to; a product that can meet it only on another of that vendor's metrics is excluded. | | `required_metrics` | string[] ([metric vocabulary](/docs/media-buy/media-buys/optimization-reporting)) | Filter to products whose `reporting_capabilities.available_metrics` is a superset of these metrics — i.e., products that commit to reporting all listed metrics in delivery. Use for capability discovery (e.g., `["completed_views"]` for a CTV CPCV buy). Sellers MUST silently exclude products that cannot meet the list — filter-not-fail; do not return an error. The product's declared `available_metrics` becomes the binding reporting contract carried into the resulting media buy. | | `required_vendor_metrics` | object[] | Filter to products whose `reporting_capabilities.vendor_metrics` covers vendor-defined metrics (proprietary attention, emissions, panel demographics, brand-lift surveys, etc.). Each entry pins `vendor` (BrandRef) and/or `metric_id` — at least one. Cross-vendor discovery (e.g., "any attention measurement") is the buyer agent's responsibility: resolve which vendors offer a category via the vendors' `brand.json` records, then enumerate them as filter entries. Same filter-not-fail semantics as `required_metrics`. | -| `audience_evidence_requirements` | AudienceEvidenceRequirements | Apply buyer-authored admissibility or ranking policy to `Product.audience_evidence`. `requirement_mode` distinguishes hard filtering from preference; `evidence_presence` distinguishes evidence-must-exist from apply-when-published. The experimental sibling `filters.target_audiences[]` names the audiences the buyer wants evidence for ([target audiences](#target-audiences-experimental)). | +| `audience_evidence_requirements` | AudienceEvidenceRequirements | Apply buyer-authored admissibility or ranking policy to `Product.audience_evidence`. `requirement_mode` distinguishes hard filtering from preference; `evidence_presence` distinguishes evidence-must-exist from apply-when-published. | | `audience_activation_methods` | object[] | **Experimental** (`media_buy.audience_activation` — check the seller's `experimental_features` before filtering; sellers that do not list the feature ignore this filter, so do not rely on it without checking. See [Experimental status](/docs/reference/experimental-status)). Filter to products whose [`audience_activation.methods`](/docs/media-buy/product-discovery/media-products#audience-activation) matches at least one requested entry (OR across entries). Within an entry every specified field must match (AND); omitted optional fields are wildcards; `directions` matches on non-empty intersection, and a method that omits `directions` matches any requested directions; `vendor` matches on `domain`, plus `brand_id` when specified. Each entry requires `pattern` ([`sync_audiences`](/docs/media-buy/task-reference/sync_audiences), `tmp_identity_match`, `file_transfer`, `dataset_query`, `clean_room`, `platform_distribution`) plus optional `vendor`, `transport`, `directions`, `buyer_agent` — fields inapplicable to the requested pattern make that entry unsatisfiable. Sellers MUST exclude products with no `audience_activation` declaration when this filter is present; exclusions MAY be reported via `filter_diagnostics.excluded_by`. | ### Audience evidence requirements @@ -484,33 +481,12 @@ Seller behavior is normative: Audience evidence does not populate `targeting_overlay`, `demographic_targeting`, or an age-verification field. If the buyer also needs exact execution, it requests that independently through the corresponding product and package targeting surfaces. -#### Target audiences (experimental) + +#### Target audiences (withdrawn) - -**Experimental** (`media_buy.audience_evidence_targets`). `target_audiences` is part of AdCP 3.3 as an experimental surface: its schemas carry `x-status: experimental`, sellers that evaluate it MUST list `media_buy.audience_evidence_targets` in `experimental_features`, and it may change between 3.x releases with notice. Check the seller's `experimental_features` before sending it. See [Experimental status](/docs/reference/experimental-status). - +The experimental `filters.target_audiences[]` (`media_buy.audience_evidence_targets`, [#8215](https://github.com/adcontextprotocol/adcp/pull/8215)) shipped on `get_products` in `3.3.0-beta.1` through `3.3.0-beta.5` and is withdrawn from this deprecated task ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). Buyers do not send it. `filters` accepts unknown fields, so a seller that does not evaluate it may ignore it rather than reject it, and a hard requirement in it would go unenforced. Its home is [`list_products`](/docs/media-buy/task-reference/list_products) `offer_filters` and [`buy_products`](/docs/media-buy/task-reference/buy_products) purchases in 4.0 (registry check [purchase_target_audiences_required_in_4_0](/docs/reference/migration/v4-compatibility#purchase_target_audiences_required_in_4_0)). Until then, express the audience preference in `audience_evidence_requirements` and the brief, and check the returned `audience_evidence_selections[]` yourself. -`target_audiences` is a sibling of `audience_evidence_requirements`, not a member of it, because the two constrain different things: the requirements above constrain evidence *quality*, and `target_audiences[]` names *which audience* the buyer cares about. `target_audiences` MUST be sent with `audience_evidence_requirements`, whose `requirement_mode`, `evidence_presence` and admissibility constraints govern it. That lets a buyer say which audience it cares about, so a buyer can ask for "evidence that at least 40% of this inventory's audience is 25–54" instead of burying the preference in the brief. - -```json -{ - "filters": { - "audience_evidence_requirements": { - "requirement_mode": "preferred", - "evidence_presence": "when_available", - "accepted_evidence_types": ["measured"], - "minimum_confidence": 0.8 - }, - "target_audiences": [ - { - "audience": { "dimension": "age", "range": { "min": 25, "max": 54 } }, - "relationship": "composition", - "minimum_value": 0.4 - } - ] - } -} -``` +The rules below still define the experimental package-level `target_audiences` on [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) packages, which `core/audience-evidence-target.json` and the package schema point to, for as long as that copy remains in 3.3. On a package, where there is no product to exclude, a seller rejects an unsatisfied `required` target rather than dropping it. Each target has an `audience` ([`audience-characteristic`](https://adcontextprotocol.org/schemas/v3/core/audience-characteristic.json)), a `relationship` (`composition`, `index`, or `reach_estimate`, the same values as `audience_evidence[].relationship`), and a `minimum_value` in the unit the relationship implies: a fraction in [0,1] for `composition`, a ratio for `index`, an integer count for `reach_estimate`. @@ -524,7 +500,6 @@ Seller behavior is normative: - A target is never a targeting predicate, impression-level proof, or legal-age verification. Hard delivery stays in `targeting_overlay.demographics`. - A seller that does not list `media_buy.audience_evidence_targets` in `experimental_features` MUST NOT apply `target_audiences`. With `requirement_mode: "required"` it MUST fail with [`UNSUPPORTED_FEATURE`](/docs/building/verification/compliance-catalog#error-code-unsupported-feature) rather than ignore the hard requirement. With `preferred` it MAY ignore the field but MUST NOT report it as applied. A 3.2 seller that validates strictly may instead return a validation error, so buyers check `experimental_features` before sending the field. - A required target a product misses is an exclusion, not an error. A seller MAY report it through `filter_diagnostics.excluded_by`. `index` targets carry no baseline in 3.3, so an index threshold is only comparable between sellers that publish the same baseline. Buyers that need to know why a product dropped out, or which targets a preferred result met, re-check the returned `audience_evidence_selections[]` against their own targets using the exact-match rule above. -- `target_audiences` is accepted on `get_products` `filters` and on `create_media_buy` packages, each as a sibling of `audience_evidence_requirements`. A [`buy_products`](/docs/media-buy/task-reference/buy_products) purchase records its terms in `product-purchase.json`, which is held closed with the commercial terms until 4.0, so purchases carry it in 4.0 rather than 3.3, and [`list_products`](/docs/media-buy/task-reference/list_products) `offer_filters` gains it with them (registry check [purchase_target_audiences_required_in_4_0](/docs/reference/migration/v4-compatibility#purchase_target_audiences_required_in_4_0)), and a purchase does not yet record the preference it was selected under. Until then, a buyer that needs an audit record keeps its own copy of the requirements and targets it sent. `audience_evidence_pins[]` identify the exact snapshots the package was built on, but a pin does not show that a target was honored. Known place IDs belong in `targeting_overlay`, so the returned product's availability, pricing, and forecast are scoped to the effective place @@ -695,7 +670,6 @@ Each entry is a discriminated union on `scope`: | `product_id` | string | Yes | Product ID from a previous `get_products` response | | `action` | string | No | `"include"` (default): return this product with updated pricing and data. `"omit"`: exclude from the response. `"more_like_this"`: find similar products (the original is also returned). When omitted, the seller treats the entry as `"include"`. | | `ask` | string | No | What the buyer is asking for. For `"include"`: specific changes (e.g., `"add 16:9 format"`). For `"more_like_this"`: what "similar" means (e.g., `"same audience but video format"`). Ignored when `action` is `"omit"`. | -| `package` | PackageForecastInput | No | Added in 3.3. Exact proposed package for a read-only availability check. Valid only with `include` (including the default). Uses the create-package field types; `pricing_option_id` and numeric `budget` are required, and the enclosing entry supplies `product_id`. Optional `impressions`, flight boundaries, targeting, formats, and other package controls retain their create semantics. See [Exact package availability](/docs/media-buy/product-discovery/refinement#check-an-exact-package-before-booking) for input resolution and required seller outcomes. | #### scope: "proposal" @@ -714,23 +688,16 @@ When the seller receives a `refine` array, the response includes `refinement_app |-------|------|----------|-------------| | `scope` | string | Yes | Echoes the scope (`"request"` / `"product"` / `"proposal"`) from the corresponding `refine` entry. | | `product_id` | string | Yes when `scope` is `"product"` | Echoes `product_id` from the corresponding refine entry. | -| `result_product_id` | string | For an applied package forecast | Added in 3.3. Identifies exactly one returned Product, even when refinement mints a configured ID. The requested pricing option and terms remain unchanged. Buyers use this ID at create. | -| `resolved_start_time`, `resolved_end_time` | date-time | With `result_product_id` | Added in 3.3. Exact forecast flight after resolving package timestamps or date-filter defaults. Buyers copy both timestamps onto the package at create. End must be after start. | | `proposal_id` | string | Yes when `scope` is `"proposal"` | Echoes `proposal_id` from the corresponding refine entry. | | `status` | string | Yes | `"applied"`: ask fulfilled. `"partial"`: partially fulfilled. `"unable"`: could not fulfill. | -| `notes` | string | Conditional | Seller explanation. Recommended when status is `"partial"` or `"unable"`; required and non-empty for a structured package entry with status `"unable"`. | - -If any request entry carries `package`, sellers MUST include the complete -position-matched `refinement_applied` array. A package entry's `applied` outcome -confirms an exact availability forecast on the returned product, even if -`fields` omitted `forecast`, and includes `result_product_id` and both resolved -timestamps so the buyer can reproduce the exact package at create. `unable` -with `notes` explains why the seller -could not compute it. A seller MUST NOT use a substitute forecast or a -`partial` outcome for that package. Insufficient inventory is `applied` with -`availability_status: "unavailable"`. Packages are forecast independently; -the call books and reserves no inventory. Without structured packages, the -existing optional-outcome behavior is unchanged. +| `notes` | string | No | Seller explanation. Recommended when status is `"partial"` or `"unable"`. | + +A product entry does not carry an exact package. The 3.3 betas added +`refine[].package` for a read-only exact-package forecast, with +`result_product_id`, `resolved_start_time` and `resolved_end_time` on the +outcome. They are withdrawn from this deprecated task +([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)), and every +`refine[]` entry rejects `package`. ### Catalog discovery @@ -773,7 +740,7 @@ result set. Otherwise confirmation remains a best practice. | `delivery_type` | string | `"guaranteed"` or `"non_guaranteed"` | | `delivery_measurement` | DeliveryMeasurement | (Optional) How delivery is measured (impressions, views, etc.) | | `pricing_options` | PricingOption[] | Available pricing models (CPM, CPCV, etc.). Auction options may include `floor_price` and optional `price_guidance`. Bid-based auction models (CPM, vCPM, CPC, CPCV, CPV) may also include optional `max_bid` (boolean). | -| `collections` | CollectionSelector[] | (Optional) Collections available in this product. A non-empty array is the complete roster; an empty array means the seller does not disclose it, and absence makes no collection declaration. A seller serving a release below 3.3 MUST NOT return a product with an empty array. See [Roster coverage](/docs/media-buy/product-discovery/media-products#roster-coverage). Each entry has `publisher_domain` and `collection_ids`. The publisher domain may be an external channel owner's. Full collection objects arrive in the response-level `collections` array when the seller includes them; otherwise buyers resolve them from the referenced `adagents.json`. See [Collections and installments](/docs/media-buy/product-discovery/collections-and-installments). | +| `collections` | CollectionSelector[] | (Optional) Collections available in this product. A non-empty array is the complete roster; an empty array means the seller does not disclose it, and absence makes no collection declaration. A seller serving a release below 3.3 MUST NOT return a product with an empty array. See [Roster coverage](/docs/media-buy/product-discovery/media-products#roster-coverage). Each entry has `publisher_domain` and `collection_ids`. The publisher domain may be an external channel owner's. Buyers resolve full collection objects from the referenced `adagents.json`. See [Collections and installments](/docs/media-buy/product-discovery/collections-and-installments). | | `collection_targeting_allowed` | boolean | (Optional, default: false) Whether buyers can target a subset of this product's `collections`. When false, the product is a bundle. | | `identity` | ProductIdentity | (Optional, experimental) Product-scoped persistent-identifier and custom reach-methodology facts. Request explicitly in a sparse response. | | `execution_requirements` | ProductExecutionRequirement[] | (Optional, experimental) Account resources a package on this product needs before [`create_media_buy`](/docs/media-buy/task-reference/create_media_buy) succeeds: `event_source`, `catalog`, or `downstream_connection`. Account-independent, so it does not change `cache_scope`. See [Product execution requirements](/docs/media-buy/specification#product-execution-requirements-experimental). Request explicitly in a sparse response. | @@ -883,7 +850,6 @@ updated `pagination.cursor`. | Field | Type | Description | |-------|------|-------------| -| `collections` | ResponseCollection[] | (Optional, experimental `media_buy.collection_cards`) Full collection objects for collections the returned products reference, one entry per `(publisher_domain, collection_id)` with `publisher_domain` required. Returned only when the request set `include_collections: true`. Sellers MUST NOT include a collection no returned product references and SHOULD include every referenced one; buyers resolve an omitted or duplicated one from `adagents.json`. Convenience copies, never authorization evidence; a copy wins over `adagents.json` only on `images`, `sample_content`, `url`, `description`, `season`, `cadence` and `distribution[].followers`. Absent when `products` is absent, and when a `fields` projection omits product `collections`. See [Collections in responses](/docs/media-buy/product-discovery/collections-and-installments#collections-in-responses). | | `property_list_applied` | boolean | [AdCP 3.0] `true` if the agent filtered products based on the provided `property_list`. Absent or `false` if not provided or not supported. | | `catalog_applied` | boolean | `true` if the seller filtered results based on the provided `catalog`. Absent or `false` if no catalog was provided or the seller does not support catalog matching. | | `refinement_applied` | [RefinementResult[]](#refinement_applied-response) | Seller acknowledgment of each `refine` entry, matched by position. Only present when `buying_mode` is `"refine"`. See [refinement_applied](#refinement_applied-response) above. | @@ -891,7 +857,6 @@ updated `pagination.cursor`. | `filter_diagnostics` | object | Optional non-fatal observability block describing how `filters` narrowed the candidate set — `total_candidates` plus per-filter `excluded_by` counts (keyed by filter name). Disambiguates "no inventory" from "your filter excluded everything" when the result list is empty or unexpectedly small. Counts only — never product names — to avoid leaking competitive intelligence. See [filter_diagnostics](#filter_diagnostics) below. | | `wholesale_feed_version` | string | Opaque token representing the version of the wholesale product feed state used to compose this response. Sellers implementing conditional-fetch (`if_wholesale_feed_version`) MUST return this on every wholesale-mode response so buyers can cache and probe later. Treat as opaque — no format, no ordering, no inspection. See [Wholesale feed versioning](#wholesale-feed-versioning). | | `pricing_version` | string | Optional opaque token representing the version of the pricing layer, including product `pricing_options` and nested `signal_targeting_options[].pricing_options`. When the seller supports independent pricing versioning, `pricing_version` changes when prices move but `wholesale_feed_version` changes only when structure/metadata moves. Sellers not separating these MAY omit `pricing_version` and use `wholesale_feed_version` for both. | -| `execution_readiness` | [ExecutionReadiness](#execution_readiness-experimental) | (Optional, experimental) Per-account readiness of the returned products' `execution_requirements`, keyed by `product_id`. Not part of the cache layer: it does not change `cache_scope` or `wholesale_feed_version`. | | `cache_scope` | string | `"public"` or `"account"`. **REQUIRED on every response** (schema-enforced — the safety property of the two-layer cache depends on it). When the request had no `account`, MUST be `"public"`. When the request had `account`, the seller declares either `"public"` (account prices off the rate card — buyer dedupes) or `"account"` (account-specific overrides). See [Cache layering](#cache-layering). | | `unchanged` | boolean | Present and `true` ONLY when the request carried `if_wholesale_feed_version` (and/or `if_pricing_version`) matching the seller's current version for the buyer's `cache_scope`, in which case `products[]` MUST be omitted; `wholesale_feed_version`, `cache_scope`, and `pricing_version` (when used) MUST still be echoed. Sellers MUST NOT emit `unchanged: false` — absence of the field IS the "response carries products" signal (one shape per state). Buyers receiving `unchanged: true` MUST NOT mutate their local wholesale product mirror. | @@ -997,31 +962,16 @@ Response (wholesale product feed changed — full payload returned, abbreviated) **Rules** - Tokens are **opaque**. No format, no ordering, no inspection. -- A returned `wholesale_feed_version` is scoped to the request parameters that produced it. Buyers MUST cache the version alongside the `(account, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, include_collections)` tuple used. An absent `include_collections` and `false` are the same scope. +- A returned `wholesale_feed_version` is scoped to the request parameters that produced it. Buyers MUST cache the version alongside the `(account, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog)` tuple used. - `pricing_version` is an optional finer-grained token: when present, it changes when prices move but `wholesale_feed_version` changes only when structure/metadata moves. Common for rate-card sweeps that don't change product metadata. - **`if_pricing_version` requires `if_wholesale_feed_version`.** Pricing has no structural baseline of its own. Sending `if_pricing_version` without `if_wholesale_feed_version` is a schema-level error. The seller's evaluation is two-stage: wholesale feed mismatch returns the full payload (pricing is implicitly stale); wholesale feed match with pricing mismatch also returns the full payload (so the buyer sees updated `pricing_options`); both match → `unchanged: true`. - **`filters` canonicalization.** Sellers MUST treat the `filters` object as canonicalized before hashing into the `wholesale_feed_version` keyspace: keys MUST be sorted lexicographically, omitted-and-default values MUST be treated identically (a missing `delivery_type` key is the same scope as `delivery_type: null`), array values MUST be sorted where the filter has set semantics (e.g., `channels`, `format_kinds`, `format_option_refs`, `required_metrics`) and preserved-order where the filter has sequence semantics (e.g., `preferred_delivery_types`). Buyers that pass equivalent-but-differently-shaped filter objects MUST receive the same `wholesale_feed_version` from the seller. This rule prevents silent stale-mirror bugs from key-order or default-elision differences between buyer SDKs. **Forward-compat default:** new filter fields added in 3.x minor versions MUST declare set-vs-sequence semantics in their schema (via `x-canonicalization: set | sequence` or equivalent prose); absent an explicit declaration, the rule defaults to **set-semantics** (sort before hashing). Sellers and SDKs that drift on this default produce cache misses that consumers can't explain. - **Pagination interaction.** `wholesale_feed_version` describes the wholesale product feed as a whole, not individual pages. Sellers MUST return `wholesale_feed_version` on every paginated page (not only the first) when they declare `wholesale_feed_versioning.supported: true`; sellers that do not declare versioning SHOULD do the same. When the wholesale feed mutates between pages, the new version surfaces on the next page and the buyer MUST restart pagination from `cursor: null` — the partial pages they've already received describe a stale version. Sellers MAY alternatively snapshot the feed at the start of pagination and serve all pages from that snapshot under the original version; either implementation is conformant as long as `wholesale_feed_version` on a given page is the version that page belongs to. - **`unchanged: true` and in-progress pagination.** A buyer that is mid-pagination on `cursor: X` MAY send `if_wholesale_feed_version` matching the version their pages so far were drawn from. If the seller confirms `unchanged: true`, the response omits `products[]` and pagination envelope entirely; the buyer abandons their in-progress walk under that version with confidence that no further pages would have produced new data. Sellers MAY NOT use the conditional-fetch short-circuit to skip individual pages within an active pagination — `unchanged` is feed-versus-cached-version, not per-page. -- **Collection copies.** `include_collections` is a scope key. Without it, [collection copies](/docs/media-buy/product-discovery/collections-and-installments#collections-in-responses) are outside `wholesale_feed_version`, so a card change alone does not make buyers who never asked for cards refetch. With `include_collections: true`, the version also changes whenever any collection copy the feed would return changes, so `unchanged: true` never hides a fresher card. A token issued under one setting and presented with the other is a mismatch and gets the full payload; sellers MUST issue distinct tokens for the two settings. Product webhooks carry no collections and their versions belong to the scope without the flag. A webhook-fed mirror keeps cards current through the experimental [`collection_card.*` events](/docs/media-buy/task-reference/list_collections#collection-card-webhooks), repaired through [`list_collections`](/docs/media-buy/task-reference/list_collections); against a seller without them, it refreshes cards through a full read with `include_collections: true`. - Pre-v3.1 sellers that ignore `if_wholesale_feed_version` simply return the full payload — semantically correct, just inefficient (same as the unchanged-server path in HTTP). For pushed change tracking beyond conditional fetch, see `specs/wholesale-feed-webhooks.md`. Wholesale feed webhooks carry the changed product payload, pricing payload, removal tombstone, or bulk-change summary; `get_products` remains the repair and reconciliation read. -### execution_readiness (experimental) - -With `include_execution_readiness: true` and an `account`, a seller that lists `media_buy.execution_readiness` in `experimental_features` returns whether the account can satisfy each returned product's [`execution_requirements`](/docs/media-buy/specification#product-execution-requirements-experimental). - -| Field | Type | Description | -|-------|------|-------------| -| `version` | string | Opaque token for the account's readiness, independent of `wholesale_feed_version` and `pricing_version`. Compare for equality only. | -| `evaluated_at` | string (date-time) | When the seller read the account's resources. | -| `products` | object | Readiness keyed by `product_id`, for returned products that declare `execution_requirements`. Each value has a rollup `readiness_status` (`ready`, `setup_required`, `selection_required`, `input_required`, `unknown`) and one `requirements[]` entry per declared requirement. | - -Each `requirements[]` entry echoes the declared `requirement` and carries `readiness_status`, plus `binding_field`, `resolved` (when `ready`), `candidates[]` (when `selection_required`), `connection_state` (for `downstream_connection`), `unknown_reason` (when `unknown`), and `issues[]`. A `candidates[].resource_id` or `resolved.resource_id` is directly usable in the binding field. `ready` does not waive binding, and `unknown` means the seller could not check, not that the account lacks the resource. See [per-account execution readiness](/docs/media-buy/specification#per-account-execution-readiness-experimental) for the full rules. - -The map is omitted on `unchanged: true` responses. Buyers cache it by `(account, version)`, never under the public key. - ### Cache layering Sellers publish two notional layers: a **public layer** (the rate-card / structural view) and **per-account overlays** (custom deals, account-specific rate cards). The conditional-fetch path is layer-aware via `cache_scope`. @@ -1032,8 +982,8 @@ Sellers publish two notional layers: a **public layer** (the rate-card / structu | Layer | Cache key | What's stored | |---|---|---| -| Public | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, include_collections)` | `wholesale_feed_version_public`, the wholesale product feed payload as seen without an account ref | -| Account overlay | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, include_collections, account_id)` | `wholesale_feed_version_account`, the wholesale product feed payload as seen WITH this account ref, when `cache_scope: "account"` was returned | +| Public | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog)` | `wholesale_feed_version_public`, the wholesale product feed payload as seen without an account ref | +| Account overlay | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, account_id)` | `wholesale_feed_version_account`, the wholesale product feed payload as seen WITH this account ref, when `cache_scope: "account"` was returned | **Behavior.** diff --git a/docs/media-buy/task-reference/list_products.mdx b/docs/media-buy/task-reference/list_products.mdx index 937e710af9b..bd0de2d8a45 100644 --- a/docs/media-buy/task-reference/list_products.mdx +++ b/docs/media-buy/task-reference/list_products.mdx @@ -34,6 +34,8 @@ Wholesale support is optional. A seller that omits `list_products` from `media_b `include_collections` (experimental, `media_buy.collection_cards`, default `false`) asks for the response-level `collections` array described below. The 3.2 schema of this request rejects unknown fields, so send it only to a seller that lists `media_buy.collection_cards` in `experimental_features`. The flag is part of the selection that `feed_version` is scoped to; see [availability forecasts](#availability-forecasts-are-a-per-read-overlay) below. +`include_execution_readiness` (experimental, `media_buy.execution_readiness`; absent means `false`) asks, together with `account`, for the response-level [`execution_readiness`](#per-account-execution-readiness-experimental) map. Opt-in because computing it can need reads on the seller's platform. Ignored without `account`. Schemas before 3.2.8 close this request, so send it only to a seller that lists `media_buy.execution_readiness` in `experimental_features`. The flag is not part of the selection that `feed_version` is scoped to. + `brand` is an identity-only key. Sellers resolve its canonical manifest from the domain; callers do not send logos, colors, or governance overrides in this request. Catalog ingestion belongs to [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs); discovery accepts only a compact catalog selection under `criteria.catalog`. `offer_filters` select commercial offers. `targeting_overlay` instead constrains the inventory or impressions that may deliver, so every returned price and forecast must account for the effective overlay. `required_overlay_support` asks for targeting dimensions the buyer can select independently on packages later. For aggregate frequency capping, use `criteria.required_media_buy_support` to require product participation and `criteria.media_buy_frequency_cap` to preflight an exact shared cap. @@ -66,6 +68,7 @@ Every response has an explicit `outcome`: | `outcome` | string | `listed` when the response contains a product page; `unchanged` when a conditional request matches the current feed. | | `products` | Product[] | Product offers for this page. Required for `listed`, even when the array is empty; omitted for `unchanged`. | | `collections` | ResponseCollection[] | Optional, experimental (`media_buy.collection_cards`). Full collection objects for collections referenced by products on this page, one entry per `(publisher_domain, collection_id)`. Returned only when the request set `include_collections: true`. Omitted with `products`, and when `fields` omits `collections`. Not authorization evidence; see [Collections in responses](/docs/media-buy/product-discovery/collections-and-installments#collections-in-responses). | +| `execution_readiness` | object | Optional, experimental (`media_buy.execution_readiness`). Per-account readiness of the page's products' `execution_requirements`, keyed by `product_id`. Returned only when the request set `include_execution_readiness: true` with an authorized `account`. Omitted with `products`. Not part of the cache layer; see [per-account execution readiness](#per-account-execution-readiness-experimental). | | `next_cursor` | string | Cursor for the next page. Omitted on the final page. Pass it as `cursor` in the next request. | | `feed_version` | string | Opaque version of the selected offer feed. Pass it as `if_feed_version` on a later request to avoid downloading an unchanged feed. | | `pricing_version` | string | Opaque version of the selected pricing layer. Pass it as `if_pricing_version` together with `if_feed_version` when checking both versions. | @@ -130,6 +133,20 @@ Availability is volatile — every booking changes it — so it is never part of In practice these are two different reads: mirror maintenance (conditional, no `forecast` in `fields`) and availability checks (`forecast` requested, never conditional). Any `availability_status` returned is a snapshot bounded by `valid_until`, never a hold — the buy itself remains the authoritative availability check and fails with [`PRODUCT_UNAVAILABLE`](/docs/building/verification/compliance-catalog#error-code-product-unavailable) when a window has since closed. +## Per-account execution readiness (experimental) + +With `include_execution_readiness: true` and an `account`, a seller that lists `media_buy.execution_readiness` in `experimental_features` returns whether the account can satisfy each listed product's [`execution_requirements`](/docs/media-buy/specification#product-execution-requirements-experimental). It moved here from the deprecated [`get_products`](/docs/media-buy/task-reference/get_products) in 3.3 ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). + +| Field | Type | Description | +|-------|------|-------------| +| `version` | string | Opaque token for the account's readiness, independent of `feed_version` and `pricing_version`. Compare for equality only. | +| `evaluated_at` | string (date-time) | When the seller read the account's resources. | +| `products` | object | Readiness keyed by `product_id`, for products on the page that declare `execution_requirements`. Each value has a rollup `readiness_status` (`ready`, `setup_required`, `selection_required`, `input_required`, `unknown`) and one `requirements[]` entry per declared requirement. A missing entry means not evaluated, not ready. | + +Each `requirements[]` entry echoes the declared `requirement` and carries `readiness_status`, plus `binding_field`, `resolved` (when `ready`), `candidates[]` (when `selection_required`), `connection_state` (for `downstream_connection`), `unknown_reason` (when `unknown`), and `issues[]`. `binding_field` names the [`buy_products`](/docs/media-buy/task-reference/buy_products) path: `purchases[].optimization_goals[].event_sources[].event_source_id` for an event source and `purchases[].catalog_ids[]` for a catalog. A `candidates[].resource_id` or `resolved.resource_id` is directly usable there. `ready` does not waive binding, and `unknown` means the seller could not check, not that the account lacks the resource. See [per-account execution readiness](/docs/media-buy/specification#per-account-execution-readiness-experimental) for the full rules. + +The map annotates and never filters: a product that is not `ready` is still listed. It is not part of the cache layer. It does not change `cache_scope`, `feed_version`, or `pricing_version`, and it is absent on an `unchanged` outcome. Buyers cache it by `(account, version)`, never under the public key, and merge pages by `product_id`. Sellers do not put it in wholesale feed webhooks. Readiness is advisory: the purchase task revalidates. + ## Wholesale feed webhooks Buyers maintaining a wholesale product mirror register `product.*` and `wholesale_feed.bulk_change` subscribers through `sync_accounts.accounts[].notification_configs[]`. Registration is account-level and durable; `push_notification_config` on an individual `list_products` request does not create that subscription. diff --git a/docs/reference/experimental-status.mdx b/docs/reference/experimental-status.mdx index f7fdfbb3706..cea278c5fa5 100644 --- a/docs/reference/experimental-status.mdx +++ b/docs/reference/experimental-status.mdx @@ -123,7 +123,7 @@ Schemas marked with `x-status: experimental` are the authoritative source. The c | `creative.signal_fanout` | The `signal_conditions[]` and `selection_strategy` inputs on [`build_creative`](/docs/creative/task-reference/build_creative), the `creatives[].signal_condition` / `selection_strategy_applied` / `estimate.conditions_total` fields on its response, the `creative.multiplicity.supports_signal_fanout` / `max_signal_conditions_limit` / `selection_strategies` capability fields on `get_adcp_capabilities`, the `enums/creative-selection-strategy.json` enum, and the `SIGNAL_TARGETING_INCOMPATIBLE` error code (#5240 / #5304, folds #5262) | New signal-driven creative fan-out surface introducing a cross-agent reject-at-trafficking MUST (`SIGNAL_TARGETING_INCOMPATIBLE`) spanning creative agent + sales agent — not yet field-tested across parties. The numeric (`value_type: numeric`) condition-compatibility comparison (range-overlap vs exact-match) is still WG-open, and the `proximity` selection strategy's geo-input binding is not yet settled — both stay revisable under experimental. Condition identity itself is resolvable today (`signal_agent_segment_id` / `signal_ref` via `get_signals`), so there is no frozen-identifier problem. | | `media_buy.audience_activation` | The [`audience_activation`](/docs/media-buy/product-discovery/media-products#audience-activation) declaration on products, the `audience_targeting.supported_activation_methods` capability field on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities), the `audience_activation_methods` product filter on [`get_products`](/docs/media-buy/task-reference/get_products), and the `core/audience-activation-method.json` schema (#4324). The cluster also covers [external audience source references](/docs/media-buy/task-reference/sync_audiences#external-audience-sources-experimental) on `sync_audiences` — the `source` request field (`core/audience-source.json`), the response `source` echo with `access_status`/`columns_read`, and the `SOURCE_ACCESS_FAILED` error code (#6540). | New activation-path discovery surface (how audience data moves: dataset sharing, clean rooms, platform distribution, file transfer) — not yet field-tested across parties. Pattern-specific field shapes (`consumer_identities[]` qualifiers, `bind_expiry_days` semantics), the grantee-identified admissibility boundary, and filter matching semantics all need integration experience with real Snowflake/Databricks/LiveRamp pipelines before freezing. The runtime leg (#6540) may reshape the declaration fields it consumes. | | `media_buy.execution_requirements` | The experimental `Product.execution_requirements` declaration on [`get_products`](/docs/media-buy/task-reference/get_products) and [`list_products`](/docs/media-buy/task-reference/list_products) results (schema: `core/product-execution-requirement.json`), and the `error-details/execution-requirement-unmet.json` details shape for the resulting `VALIDATION_ERROR` on `create_media_buy` and `update_media_buy` (#7763) | First, account-independent half of the execution-readiness RFC. The requirement kinds and their binding points reuse existing request fields, but the vocabulary is expected to grow (lead forms, messaging destinations) and per-account readiness — which resources an account has and which one to use — is the separate `media_buy.execution_readiness` surface below and may reshape how requirements and readiness compose. | -| `media_buy.execution_readiness` | The `include_execution_readiness` request field and response-level `execution_readiness` map on [`get_products`](/docs/media-buy/task-reference/get_products) (schemas: `core/product-execution-readiness.json`, `core/execution-requirement-readiness.json`, `enums/execution-readiness-status.json`) (#7763) | Second, account-scoped half of the execution-readiness RFC. It reports `ready`, `setup_required`, `selection_required`, `input_required`, or `unknown` per declared requirement, with account-scoped candidates. Identity selection, lead-form and messaging-destination requirements, and proposal bindings are not specified yet and may change how readiness composes with requirements. | +| `media_buy.execution_readiness` | The `include_execution_readiness` request field and response-level `execution_readiness` map on [`list_products`](/docs/media-buy/task-reference/list_products#per-account-execution-readiness-experimental) (schemas: `core/product-execution-readiness.json`, `core/execution-requirement-readiness.json`, `enums/execution-readiness-status.json`) (#7763). The 3.3 betas carried it on `get_products`; it moved to `list_products` before GA (#8501). | Second, account-scoped half of the execution-readiness RFC. It reports `ready`, `setup_required`, `selection_required`, `input_required`, or `unknown` per declared requirement, with account-scoped candidates. Identity selection, lead-form and messaging-destination requirements, and proposal bindings are not specified yet and may change how readiness composes with requirements. | | `signals.delivery_methods` | The `signals.delivery_methods[]` capability on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) (schema: `core/signal-delivery-method.json`), the `delivery_method` pin on agent destinations, and the `delivery_status` (`enums/signal-delivery-status.json`), `delivery`, `delivery_error`, `match_status`, `matched_count`, `effective_match_rate`, `match_rate_basis`, `audience_size` fields on agent [`activate_signal`](/docs/signals/tasks/activate_signal#delivering-membership-to-agent-destinations-experimental) deployments (#6552) | Provider-initiated membership delivery to agent destinations consumes the experimental `media_buy.audience_activation` vocabulary and has a single implementer pull so far (a publisher ad-server seller agent). Rail-selection authority, the arrival-state vocabulary, and match-outcome placement need integration experience across real signal-agent and seller pairs before freezing. Delivery cost is absorbed in the signal price for now; rail-dependent fee declarations may follow. | | `media_buy.gender_targeting` | Core `demographics.gender` predicates, product gender capabilities and overlay support/requirements, exact gender and mixed age/gender targeting resolution, the gender capability rollup, authoritative signal gender metadata, and the `sex_gender` governance classification — see [Core gender targeting](/docs/media-buy/advanced-topics/targeting#core-gender-targeting-33). Stable age targeting is excluded. | New portable gender contract without multi-party adoption evidence. Canonical demographic delivery reporting remains age-only in 3.3; this experiment does not add gendered delivery readback. | | `media_buy.product_identity` | The experimental `Product.identity` declaration on [`get_products`](/docs/media-buy/product-discovery/media-products) and [`list_products`](/docs/media-buy/task-reference/list_products) results, plus reach-unit coherence in delivery reporting | Product-level identity availability, the boundary between modeled and identifier-backed reach, and the methodology disclosure remain new cross-channel interoperability semantics. The field is deliberately product-scoped so mixed addressable and non-addressable inventory remains truthful while implementers validate the disclosure and reporting behavior. | @@ -146,16 +146,15 @@ Schemas marked with `x-status: experimental` are the authoritative source. The c | `media_buy.collection_catalog` | [`list_collections`](/docs/media-buy/task-reference/list_collections) (schemas: `media-buy/list-collections-request.json`, `media-buy/list-collections-response.json`), its `collections_version` / `if_collections_version` tokens, and the `collection_card.updated`, `collection_card.removed` and `collection_catalog.bulk_change` webhook event types (branches of `core/wholesale-feed-event.json`, delivered in `core/wholesale-feed-webhook.json` and listed in `wholesale_feed_webhooks.event_types`) ([#8183](https://github.com/adcontextprotocol/adcp/issues/8183)) | Standalone catalog read and push channel for collection cards, with one adopter behind the card surface so far (Availnet, a creator marketplace) and no emitting agent yet. Requires `media_buy.collection_cards`, because the response carries card fields; a seller can serve cards in-band without it. Webhooks are optional within the feature and declared per type. The filter set, the reuse of the wholesale feed envelope with `collections_version` in `wholesale_feed_version`, and the bulk threshold for follower sweeps may change. Not served to callers below 3.3. Storyboards and a `seed_collection` controller scenario wait for training-agent support ([#8181](https://github.com/adcontextprotocol/adcp/issues/8181)). | | `media_buy.installment_holds` | The committed proposal's `holds` array (`core/canonical-proposal.json`): `product_id`, `installment_ref`, and, under a rankable policy, `hold_rank` for each installment the hold covers, described in [Installment holds](/docs/media-buy/task-reference/refine_proposals#installment-holds-experimental) ([#8086](https://github.com/adcontextprotocol/adcp/issues/8086)) | One named adopter so far: Availnet, a creator marketplace, where the held unit is a creator's specific upcoming video. Readback only: entries describe one all-or-none hold and share the proposal's `expires_at`, so there are no partial holds. Whether entries need their own `expires_at`, which only makes sense if partial holds are ever allowed, needs field experience. Requires `media_buy.hold_policy`; omitted for callers below 3.3. | | `identity.trust_json` | The `trust/v1/trust.json` and `trust/v1/trust-acknowledgements.json` schemas, described in [trust.json (experimental)](/docs/reference/trust-json) ([RFC #7809](https://github.com/adcontextprotocol/adcp/issues/7809), [#7819](https://github.com/adcontextprotocol/adcp/pull/7819)). In 3.3 its reader is the experimental Web Bot Auth signing profile, which derives a trust record from an agent's origin ([Web Bot Auth identities](/docs/building/by-layer/L1/security#web-bot-auth-identities)); grants are read at `sync_accounts` and on the freshness schedule ([Grants in trust records](/docs/building/by-layer/L2/accounts-and-agents#grants-in-trust-records-experimental), [DR-0025](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0025-demand-side-grants-in-trust-json.md)). No one is required to publish `/.well-known/trust.json`, and publishing one is not implementing a task, so publishers declare nothing in `experimental_features`. | The document shape for agents, grants, and acknowledgements is published ahead of the behavior that would use it, so implementers can review it. Agents are identified by origin, one per origin, and the record carries no keys ([`specs/agent-identity-3-3.md`](https://github.com/adcontextprotocol/adcp/blob/main/specs/agent-identity-3-3.md)). The document name and its `/.well-known` path may change before graduation: the JournalList `trust.txt` naming outreach is still open. The record's location is derived from the agent's origin, so no capability pointer is planned. Resolution and no-downgrade rules are in the Web Bot Auth identities section of the security page. | -| `media_buy.collection_cards` | The `images`, `sample_content` and `url` fields on `core/collection.json`, the `brand_ref` field on `core/talent.json`, the `sample_content` role on `core/product-card-reference-asset.json` (#8092), and the `followers` field on `core/collection-distribution.json` entries, a `core/audience-size.json` count (#8098); the top-level `collections` array (`core/response-collection.json`) on the `get_products`, `list_products`, `request_proposals` and `refine_proposals` responses, and the `include_collections` request flag that opts into it (#8137). See [collection cards](/docs/media-buy/product-discovery/collections-and-installments#collection-cards-experimental). | Display and identity slice of the creator-card RFC, with a single adopter so far (Availnet, a creator marketplace) and no field-testing across parties yet. The array bounds, the use of `published-post` references for samples, the `brand_ref`-over-`brand_url` precedence, the opt-in flag, and the closed list of fields (`images`, `sample_content`, `url`, `description`, `season`, `cadence`, `distribution[].followers`) on which a response copy wins over `adagents.json` may change. `adagents.json` publishers cannot declare `experimental_features`, so consumers treat the collection fields as experimental wherever they appear. Sellers that emit the `sample_content` role or response `collections`, or accept `include_collections`, declare the id. Whether a follower count belongs on the distribution entry, and how sellers report platform-rounded counts, may change. Audience composition (`audience_evidence`) and average views (forecast `views`) reuse existing surfaces and are not part of this surface. | +| `media_buy.collection_cards` | The `images`, `sample_content` and `url` fields on `core/collection.json`, the `brand_ref` field on `core/talent.json`, the `sample_content` role on `core/product-card-reference-asset.json` (#8092), and the `followers` field on `core/collection-distribution.json` entries, a `core/audience-size.json` count (#8098); the top-level `collections` array (`core/response-collection.json`) on the `list_products`, `request_proposals` and `refine_proposals` responses, and the `include_collections` request flag that opts into it (#8137). The 3.3 betas also carried both on the deprecated `get_products`; they are withdrawn from it (#8501). See [collection cards](/docs/media-buy/product-discovery/collections-and-installments#collection-cards-experimental). | Display and identity slice of the creator-card RFC, with a single adopter so far (Availnet, a creator marketplace) and no field-testing across parties yet. The array bounds, the use of `published-post` references for samples, the `brand_ref`-over-`brand_url` precedence, the opt-in flag, and the closed list of fields (`images`, `sample_content`, `url`, `description`, `season`, `cadence`, `distribution[].followers`) on which a response copy wins over `adagents.json` may change. `adagents.json` publishers cannot declare `experimental_features`, so consumers treat the collection fields as experimental wherever they appear. Sellers that emit the `sample_content` role or response `collections`, or accept `include_collections`, declare the id. Whether a follower count belongs on the distribution entry, and how sellers report platform-rounded counts, may change. Audience composition (`audience_evidence`) and average views (forecast `views`) reuse existing surfaces and are not part of this surface. | | `brand.collection_links` | The `collections` field on the [`get_brand_identity`](/docs/brand-protocol/tasks/get_brand_identity) response and its `collections` value in the request `fields` and response `available_fields` lists, plus `publisher_domain` on `brand.json` brand-level collection links (#8137) | Brand-side half of the creator-card work: lets a buyer go from a talent's `brand_ref` to the person's channels and confirm the link from both sides. One adopter so far (Availnet, a creator marketplace). The link shape, the public visibility level, and whether `seller_agent_url` stays on the link may change. `brand.json` publishers cannot declare `experimental_features`, so consumers treat `publisher_domain` there as experimental. Brand agents that return `collections` declare the id. | | `signals.signal_lifecycle` | The optional `signal_status` (`enums/signal-status.json`: `processing`, `ready`, `failed`; absent means `ready`) and `source_audience_id` fields on [`get_signals`](/docs/signals/tasks/get_signals) results, the matching `fields` projection values, and the `signals.features.signal_lifecycle` capability flag on [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) (#5409; see [Custom segments built from a seed audience](/docs/signals/tasks/get_signals#custom-segments-built-from-a-seed-audience)) | Readiness and seed lineage for segments a signal agent builds on demand, driven so far by a single named adopter. The wholesale-feed-version and buyer-scoping rules, and the `processing` vocabulary shared with `audience-status`, may change once more signal agents build segments. | | `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.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 `audience_evidence_requirements` because the two constrain different things: which audience, and the quality of the evidence. The `buy_products` purchase input (`media-buy/product-purchase-input.json`) and the `list_products` `offer_filters` (`core/product-offer-filters.json`) are open in 3.3 but do not define it. It is defined 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 echo in the accepted purchase snapshot, `media-buy/product-purchase.json`, which is held closed with the commercial terms until 4.0. 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. | +| `media_buy.audience_evidence_targets` | The `target_audiences[]` field, a sibling of `audience_evidence_requirements` on `media-buy/package-request.json` (`create_media_buy` packages; the 3.3 betas also carried it on `get_products` `filters`, withdrawn by #8501), 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 `audience_evidence_requirements` because the two constrain different things: which audience, and the quality of the evidence. The `buy_products` purchase input (`media-buy/product-purchase-input.json`) and the `list_products` `offer_filters` (`core/product-offer-filters.json`) are open in 3.3 but do not define it. It is defined 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 echo in the accepted purchase snapshot, `media-buy/product-purchase.json`, which is held closed with the commercial terms until 4.0. 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. | -| `media_buy.price_adjustments` | The `price_adjustments` table on fixed-price pricing options (not embedded in accepted purchase `pricing`: the accepted `pricing_option_id` pins one immutable table, and embedding it is a 4.0 item, #8501), its fee and discount rows (applied in declared order to one running total) and validity windows, and `error-details/price-adjustments-mismatch.json` ([selection-dependent price adjustments](/docs/media-buy/advanced-topics/pricing-models#selection-dependent-price-adjustments)) | One named pilot (Dutch linear TV rate cards) and one RFC, with the field set still growing: position in break, audience, activation method, and measurement vendor have no selectable anchor yet, a dimension can fire only one row in 3.3, and per-installment resolution of a flight that crosses a validity window is open. A seller must not return a table to callers below 3.3. | Graduation progress and notice of upcoming breaking changes will be called out in the [release notes](/docs/reference/release-notes) for each 3.x release starting with 3.0 GA. diff --git a/docs/reference/migration/v4-compatibility.mdx b/docs/reference/migration/v4-compatibility.mdx index 891ee468bea..81182ff8741 100644 --- a/docs/reference/migration/v4-compatibility.mdx +++ b/docs/reference/migration/v4-compatibility.mdx @@ -134,7 +134,7 @@ No storyboard step inspects every annotated field, so the suite reports this che **Detects:** a seller that lists `media_buy.audience_evidence_targets` in `experimental_features` does not accept `target_audiences` on `buy_products` purchases and `list_products` `offer_filters`. -In 3.3 the experimental `target_audiences[]` is a sibling of `audience_evidence_requirements` on `get_products` filters and on `create_media_buy` packages. A purchase records its terms in `product-purchase.json`, which is held closed with the commercial terms until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)), so `buy_products` purchases gain the field in 4.0, and `list_products` `offer_filters` gains it with them. +In 3.3 the experimental `target_audiences[]` is a sibling of `audience_evidence_requirements` on `create_media_buy` packages. It was also on `get_products` filters through `3.3.0-beta.5` and is withdrawn from that deprecated task ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). A purchase records its terms in `product-purchase.json`, which is held closed with the commercial terms until 4.0 ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)), so `buy_products` purchases gain the field in 4.0, and `list_products` `offer_filters` gains it with them. **Fix:** accept the sibling on those surfaces and record it in the accepted purchase snapshot. Until 4.0, a buyer that needs an audit record keeps its own copy of the requirements and targets it sent. A 3.x run cannot observe this check, so it reports as not observable. @@ -221,6 +221,24 @@ In 3.3 the experimental `billing_measurement.counting_mechanisms[]` is carried o **Fix:** declare `counting_mechanisms` on the canonical terms as well. A 3.x run cannot observe this check, so it reports as not observable. + +### Canonical pricing options carry price adjustments + +**Check id:** `canonical_price_adjustments_required_in_4_0` · **Change:** new requirement · **Issue:** [#7659](https://github.com/adcontextprotocol/adcp/issues/7659) + +**What it was:** experimental `media_buy.price_adjustments`, an ordered table of fee and discount rows on a fixed-price pricing option, so a buyer can compute the binding rate for its format option and placement selections and its flight dates without another quote ([#7955](https://github.com/adcontextprotocol/adcp/pull/7955)). It shipped in `3.3.0-beta.1` through `3.3.0-beta.5` on the pricing options of the deprecated `get_products` and is withdrawn after beta.5 ([adcp#8501](https://github.com/adcontextprotocol/adcp/issues/8501)): 3.3 adds no field that exists only on a deprecated task, and `core/canonical-pricing-option.json` is held closed with the commercial terms until 4.0. + +**Design to keep:** + +- Composition is one running total in declared order. Each firing row adds (`fee`) or subtracts (`discount`) the rounded product of the running total and its rate, or its amount. Selection rows fire once per dimension; `always` rows each fire; `valid_from` / `valid_until` bound a row at the purchase start. +- Any change to the table mints a new `pricing_option_id`, so the accepted `pricing_option_id` identifies one immutable table that both parties price from. +- When the buyer supplies `pricing`, a seller rejects a price that differs from the resolved result with `INVALID_REQUEST` and the resolved values in `error-details/price-adjustments-mismatch.json`. +- A placement-selection row requires `overlay_support.placement_selection` on the product. + +**Where it is preserved:** commit `4c35f8ce1` (#7955) carries `pricing-options/price-adjustments.json`, `error-details/price-adjustments-mismatch.json`, the rule on the seven fixed-price pricing options, the vectors in `static/compliance/source/test-vectors/price-adjustments/` with `tests/price-adjustments-vectors.test.cjs`, and the section "Selection-dependent price adjustments" in `docs/media-buy/advanced-topics/pricing-models.mdx`. The `3.3.0-beta.1` to `3.3.0-beta.5` bundles under `dist/` keep the schemas. + +**Until then:** return a priced option per configured product. **What 4.0 needs:** the table on the canonical pricing option, and a rule for how `terms_digest` binds the table an accepted `pricing_option_id` names. + ## Changes not checked yet A check is added once its 4.0 change is decided. These changes are still proposals or under working group review, so the suite does not grade them yet: diff --git a/docs/reference/test-vectors/index.mdx b/docs/reference/test-vectors/index.mdx index 09ddae95a92..3c768a9aa71 100644 --- a/docs/reference/test-vectors/index.mdx +++ b/docs/reference/test-vectors/index.mdx @@ -51,7 +51,6 @@ SDKs SHOULD fetch versioned paths where available and record the version under t | [`oauth-setup`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/oauth-setup) | OAuth metadata-graph conformance: deterministic network fixtures for `oauth_metadata_graph` checks, redirect validation, graph-budget enforcement, and fail-closed behavior for missing fixture responses. No live network access permitted | `static/compliance/source/test-vectors/oauth-setup/` | `/compliance/latest/test-vectors/oauth-setup/` | | [`trusted-match-context-merge`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/trusted-match-context-merge) | Context Match targeting key-value merge: router attribution from publisher-controlled provider registration, bucket-key derivation, provider `signals.targeting_kvs` pass-through, shared-key multi-provider contribution, and dropped unmapped/case-mismatched tuples | `static/compliance/source/test-vectors/trusted-match-context-merge/` | `/compliance/latest/test-vectors/trusted-match-context-merge/` | | [`products-only-brief-compatibility`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/products-only-brief-compatibility) | Products-only brief flow across AdCP 2.5, 3.0, 3.1: compact projection without invented proposals, fail-closed legacy-create continuation with named fences, seller-fenced `listed_purchase` feed/pricing propagation, and 3.2 reverse-compatibility facades | `static/compliance/source/test-vectors/products-only-brief-compatibility/` | `/compliance/latest/test-vectors/products-only-brief-compatibility/` | -| [`price-adjustments`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/price-adjustments) | Deterministic resolution of selection-dependent `price_adjustments`: one row per dimension (first match), sequential running total in declared order (index cards as fee and discount rates), quote binding to account and expiry, accepted terms pricing a permitted change without granting one, half-away-from-zero rounding at option price precision (JPY, sub-cent `cpv`), declared-breakdown composition, cross-encoding and cross-scope selector identity, below-zero rejection, buyer-pricing mismatch, new-ID-on-change, and schema negatives (next 3.3 beta) | `static/compliance/source/test-vectors/price-adjustments/` | `/compliance/latest/test-vectors/price-adjustments/` | | [`error-recovery`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/error-recovery) | Version-gated 3.2 recovery emission and compatible 3.1 decoding: known/unknown codes with and without `recovery`, buyer-reason consistency, bounded fallback retries, and `retry_after` scheduling including legacy fractions | `static/compliance/source/test-vectors/error-recovery/` | `/compliance/latest/test-vectors/error-recovery/` | | [`reporting-reconciliation`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/reporting-reconciliation) | Managed-reporting reconciliation: exact manifest/object/receipt bytes, canonical logical rows, SHA-256 and SHA-512 evidence, retry/permanent classifications, integrity mutations, receipt idempotency, and uncertain-write checkpoint recovery | `static/compliance/source/test-vectors/reporting-reconciliation/` | `/compliance/latest/test-vectors/reporting-reconciliation/` | | [`reporting-subscriptions`](https://github.com/adcontextprotocol/adcp/tree/main/static/compliance/source/test-vectors/reporting-subscriptions) | Experimental reporting-subscription coverage (`media_buy.reporting_subscriptions`): every period a subscription owes per buy and resolved offering, from the start bound, the confirmation period, flights as of each period end, cutovers between versions, resolutions, and timezones, deactivation and reactivation, authorization chains and gaps, exceptions, selection, and period generation across DST transitions at midnight, 30-minute DST, non-hour offsets, month-end clamps, and weeks and years. The set also freezes the SDK error codes (`error-codes.json`) and the coverage reason codes (`reason-codes.json`). Expected rows use a pinned IANA tzdata release, and a brute-force reference model in `scripts/reference/reporting-coverage` reproduces every case | `static/compliance/source/test-vectors/reporting-subscriptions/` | `/compliance/latest/test-vectors/reporting-subscriptions/` | diff --git a/package.json b/package.json index 5ddf48949ed..8ef4e753a59 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/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/assignment-replace.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/url-pattern-loosening.test.cjs tests/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.test.cjs tests/match-keys.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/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/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/seller-offers-contract.test.cjs tests/service-commitments.test.cjs tests/sync-platform-id.test.cjs tests/assignment-landing-page.test.cjs tests/assignment-trackers.test.cjs tests/assignment-replace.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/catalog-ingestion-capabilities.test.cjs tests/sdk-implementation-metadata.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/terminal-package-retention-storyboard.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/x-added-in-3-3-sweep.test.cjs tests/url-pattern-loosening.test.cjs tests/performance-standard-metric-id.test.cjs tests/identity-absence-coherence.test.cjs tests/match-keys.test.cjs tests/execution-requirements.test.cjs tests/execution-readiness.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/creative-start-policy.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-live-updates.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/print-metrics.test.cjs tests/installment-lifecycle-reporting.test.cjs tests/rights-channel-restrictions.test.cjs tests/daypart-time-of-day.test.cjs tests/audience-size-range.test.cjs tests/media-buy-lineage.test.cjs tests/delivery-projection.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/collection-mechanism.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/property-delivery-conformance.test.cjs tests/lint-schema-enum-drift.test.cjs tests/lint-schema-required-declared.test.cjs tests/format-asset-type-parity.test.cjs tests/canonical-manifest-constructibility.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/mutation-outcome.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs tests/trust-json-v1.test.cjs tests/refine-proposals-expected-confirmation-at.test.cjs tests/hold-policy.test.cjs tests/hold-policy-vectors.test.cjs tests/canonical-installments.test.cjs tests/withdrawn-to-4-0.test.cjs tests/get-products-deprecated-withdrawals.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/scripts/oneof-discriminators.baseline.json b/scripts/oneof-discriminators.baseline.json index f5bf0ce3d09..6d70944a377 100644 --- a/scripts/oneof-discriminators.baseline.json +++ b/scripts/oneof-discriminators.baseline.json @@ -331,21 +331,6 @@ "variants": 2, "note": "shared-required=[∅]; 0:number | 1:req=[duration_seconds]" }, - "pricing-options/price-adjustments.json##/items/oneOf/0/oneOf": { - "kind": "narrowable", - "variants": 2, - "note": "0:[rate] | 1:[amount]" - }, - "pricing-options/price-adjustments.json##/items/oneOf/1/oneOf": { - "kind": "narrowable", - "variants": 2, - "note": "0:[rate] | 1:[amount]" - }, - "pricing-options/price-adjustments.json##/items/oneOf/2/oneOf": { - "kind": "narrowable", - "variants": 2, - "note": "0:[rate] | 1:[amount]" - }, "pricing-options/price-breakdown.json##/properties/adjustments/items/oneOf": { "kind": "narrowable", "variants": 2, diff --git a/server/src/training-agent/collections/include-collections.ts b/server/src/training-agent/collections/include-collections.ts index b0a6eba7ffb..1b8830bb287 100644 --- a/server/src/training-agent/collections/include-collections.ts +++ b/server/src/training-agent/collections/include-collections.ts @@ -1,8 +1,11 @@ /** - * `include_collections` on `get_products`, `list_products`, - * `request_proposals` and `refine_proposals` (experimental, - * `media_buy.collection_cards`, #8094/#8141). See - * collections-and-installments.mdx, "Collections in responses". + * `include_collections` on `list_products`, `request_proposals` and + * `refine_proposals` (experimental, `media_buy.collection_cards`, + * #8094/#8141). See collections-and-installments.mdx, "Collections in + * responses". The flag was withdrawn from the deprecated `get_products` in + * 3.3 (adcp#8501): a `get_products` read still gets the `sample_content` + * card projection below, but never the `collections` array or a cards-scoped + * feed token. * * - Opt-in: `collections` is returned only when the request set * `include_collections: true`, and only to a caller served 3.3 or later. @@ -44,12 +47,10 @@ interface CardsContext { const CARDS_SCOPE_MARKER = '~cards.'; const CONDITIONAL_FIELD: Partial> = { - get_products: 'if_wholesale_feed_version', list_products: 'if_feed_version', }; const VERSION_FIELD: Partial> = { - get_products: 'wholesale_feed_version', list_products: 'feed_version', }; @@ -57,7 +58,12 @@ function isRecord(value: unknown): value is Record { return typeof value === 'object' && value !== null && !Array.isArray(value); } -export function collectionsRequested(args: Record, ctx: CardsContext): boolean { +export function collectionsRequested( + args: Record, + ctx: CardsContext, + tool?: CollectionReadTool, +): boolean { + if (tool === 'get_products') return false; return supportsCollections33(ctx.servedAdcpVersion) && args.include_collections === true; } @@ -78,7 +84,7 @@ export function prepareCollectionRead( ctx: CardsContext, ): Record { const field = CONDITIONAL_FIELD[tool]; - if (!field || typeof args[field] !== 'string' || !collectionsRequested(args, ctx)) return args; + if (!field || typeof args[field] !== 'string' || !collectionsRequested(args, ctx, tool)) return args; const presented = args[field] as string; const suffix = cardsScopeSuffix(ctx); return { @@ -157,7 +163,7 @@ export function finishCollectionRead( const record: Record = result; const products = Array.isArray(record.products) ? record.products : undefined; if (products) projectSampleContentRole(products); - if (!collectionsRequested(args, ctx)) return result; + if (!collectionsRequested(args, ctx, tool)) return result; const versionField = VERSION_FIELD[tool]; if (versionField && typeof record[versionField] === 'string') { record[versionField] = `${record[versionField] as string}${cardsScopeSuffix(ctx)}`; diff --git a/server/src/training-agent/task-handlers.ts b/server/src/training-agent/task-handlers.ts index e966eb36377..d438a59ebbb 100644 --- a/server/src/training-agent/task-handlers.ts +++ b/server/src/training-agent/task-handlers.ts @@ -12089,7 +12089,7 @@ async function handleGetProductsUnlocked( // is intentionally not part of the deprecated get_products wire schema. type RefineEntry = | { scope: 'request'; ask?: string } - | { scope: 'product'; product_id: string; action?: 'include' | 'omit' | 'more_like_this'; ask?: string; package?: Record } + | { scope: 'product'; product_id: string; action?: 'include' | 'omit' | 'more_like_this'; ask?: string } | { scope: 'proposal'; proposal_id: string; @@ -12121,7 +12121,6 @@ async function handleGetProductsUnlocked( : [], ); const refinementApplied: RefinementAppliedEntry[] = []; - const unsupportedPackageForecastIds = new Set(); const proposalOmitIds = new Set(); const refinedProposalOverrides = new Map(); const explicitlySelectedProposals = new Map(); @@ -12308,16 +12307,6 @@ async function handleGetProductsUnlocked( refinementApplied.push({ scope: 'product', product_id: op.product_id, status: 'applied' }); } else if (action === 'include') { includeIds.add(op.product_id); - if (op.package !== undefined) { - unsupportedPackageForecastIds.add(op.product_id); - refinementApplied.push({ - scope: 'product', - product_id: op.product_id, - status: 'unable', - notes: 'The training agent cannot compute an availability forecast for an exact proposed package.', - }); - continue; - } if (!passesFilters) { refinementApplied.push({ scope: 'product', @@ -13185,20 +13174,10 @@ async function handleGetProductsUnlocked( } // Store context for refine - const responseProducts = products.map(product => { - const servedProduct = productForServedAdcpVersion( - isThreeZeroStoryboardCompat(ctx) ? productForThreeZeroStoryboardCompat(product) : product, - ctx.servedAdcpVersion, - ); - // Suppress ordinary/horizon forecasts after every generic forecast path; - // none is evidence that the unsupported exact package was evaluated. - const sourceProductId = discoverySourceProductIds.get(product.product_id) ?? product.product_id; - if (!unsupportedPackageForecastIds.has(sourceProductId) - && !unsupportedPackageForecastIds.has(product.product_id)) return servedProduct; - const withoutForecast = { ...servedProduct }; - delete withoutForecast.forecast; - return withoutForecast; - }); + const responseProducts = products.map(product => productForServedAdcpVersion( + isThreeZeroStoryboardCompat(ctx) ? productForThreeZeroStoryboardCompat(product) : product, + ctx.servedAdcpVersion, + )); const retainedCommittedProposals = new Map( (session.lastGetProductsContext?.proposals ?? []) .filter(proposal => proposalLifecycle(proposal).proposal_status === 'committed') @@ -18565,6 +18544,24 @@ export async function handleSyncCreatives(args: ToolArgs, ctx: TrainingContext) errors: [{ code: 'INVALID_REQUEST', message: 'At least one of creatives, assignments, or assignment_operations is required' }] as TaskError[], }; } + // trackers and landing_page_url were withdrawn from the deprecated + // assignments[] row in 3.3 (adcp#8501); assignment_operations assign carries + // them. The row rejects them by name, and so does the agent, rather than + // silently dropping them. + const legacyAssignments = (req.assignments ?? []) as unknown as Array>; + for (let index = 0; index < legacyAssignments.length; index++) { + for (const field of ['trackers', 'landing_page_url'] as const) { + if (isRecord(legacyAssignments[index]) && legacyAssignments[index]![field] !== undefined) { + return { + errors: [{ + code: 'INVALID_REQUEST', + message: `assignments[${index}].${field} is not defined on the deprecated assignments row; send it on an assignment_operations assign operation.`, + field: `assignments[${index}].${field}`, + }] as TaskError[], + }; + } + } + } if (assignmentOperations?.length && (req as unknown as { validation_mode?: string }).validation_mode === 'lenient') { return { errors: [{ code: 'INVALID_REQUEST', message: 'assignment_operations are atomic and require validation_mode strict.', field: 'validation_mode' }] as TaskError[], @@ -25232,8 +25229,10 @@ function validateIdempotencyProtectedInput( return { message: 'brief must be a string when provided', field: 'brief' }; } if (Array.isArray(args.refine) && args.refine.some(entry => isRecord(entry) && 'package' in entry)) { - // The pinned SDK preserves unknown entry fields. Validate structured - // packages against source before replay claims or downstream state changes. + // refine[].package was withdrawn from 3.3 (adcp#8501). The pinned SDK + // preserves unknown entry fields, so validate against source, whose + // entries reject it by name, before replay claims or state changes. + // A facade rejects a field it cannot honor rather than dropping it. const sourceError = validateProductDiscoverySourceInput('get-products-request', args); if (sourceError) return sourceError; } diff --git a/server/src/training-agent/tenants/router.ts b/server/src/training-agent/tenants/router.ts index 7ab44c3baa5..d5e6664b1c3 100644 --- a/server/src/training-agent/tenants/router.ts +++ b/server/src/training-agent/tenants/router.ts @@ -1069,13 +1069,15 @@ function projectTenantToolDiscovery( // Experimental 3.3 include_collections (#8181): only a listing served // at 3.3 or later advertises the flag. The SDK stamps the listing's // release on the result; under the `all` tool profile it does not shape - // input schemas to it. + // input schemas to it. get_products never advertises it: the flag was + // withdrawn from the deprecated task in 3.3 (adcp#8501). const listingMeta = (parsed.result as { _meta?: { adcp_version?: unknown } } | undefined)?._meta; for (const tool of tools) { const listedAt = listingMeta?.adcp_version ?? (tool as { _meta?: { adcp_version?: unknown } })._meta?.adcp_version; const properties = tool.inputSchema?.properties; if (!properties || !('include_collections' in properties)) continue; - if (supportsCollections33(typeof listedAt === 'string' ? listedAt : undefined)) continue; + if (tool.name !== 'get_products' + && supportsCollections33(typeof listedAt === 'string' ? listedAt : undefined)) continue; const { include_collections: _flag, ...rest } = properties; tool.inputSchema = { ...tool.inputSchema, properties: rest }; } diff --git a/server/src/training-agent/tenants/served-release-shape.test.ts b/server/src/training-agent/tenants/served-release-shape.test.ts index afc6052db5c..ac13044172f 100644 --- a/server/src/training-agent/tenants/served-release-shape.test.ts +++ b/server/src/training-agent/tenants/served-release-shape.test.ts @@ -149,9 +149,9 @@ function argsFor(tool: string, label: string, version: string, state: FlowState) const image = { asset_type: 'image', url: 'https://cdn.example.com/served-release.png', width: 300, height: 250 }; switch (tool) { case 'get_products': - // Every release is asked for collection cards (experimental 3.3, - // #8181): get_products accepts unknown fields, so a stable caller's - // flag is ignored and only the preview answers with `collections`. + // Every release still sends include_collections: get_products accepts + // unknown fields and the flag was withdrawn from it (adcp#8501), so no + // release answers with `collections`; list_products carries them. return { buying_mode: 'brief', brief: 'Display and video for sports fans in the US', include_collections: true }; case 'create_media_buy': { const product = state.products?.find(candidate => { @@ -409,14 +409,8 @@ describe('served-release response shape below 3.3 (#8487)', () => { )))}`); } if (tool === 'get_products') { - const isPreview = version === TRAINING_AGENT_HOSTED_PREVIEW.wireVersion; - const referencesCollections = (structured.products as Array>) - .some(product => Array.isArray(product.collections) && product.collections.length > 0); - if (!isPreview && structured.collections !== undefined) { - failures.push(`${label} get_products @${version}: collection cards served to a stable caller`); - } - if (isPreview && referencesCollections && !Array.isArray(structured.collections)) { - failures.push(`${label} get_products @${version}: include_collections answered without collections`); + if (structured.collections !== undefined) { + failures.push(`${label} get_products @${version}: served collection cards (withdrawn from get_products, adcp#8501)`); } } // A 3.0 product card is a format reference plus its manifest; the @@ -465,8 +459,10 @@ describe('served-release response shape below 3.3 (#8487)', () => { const failures: string[] = []; // Preview reads first: they must not leave anything behind that a later // stable read of the shared catalog could see. + // get_products no longer returns cards even at the preview, but keeps the + // sample_content card projection (adcp#8501). const previewProducts = await call(sales, 'get_products', { adcp_version: preview, ...brief }); - expect(Array.isArray(previewProducts.structured?.collections), JSON.stringify(previewProducts.raw).slice(0, 300)).toBe(true); + expect(previewProducts.structured?.collections, JSON.stringify(previewProducts.raw).slice(0, 300)).toBeUndefined(); expect(JSON.stringify(previewProducts.structured)).toContain('"sample_content"'); await call(`${baseUrl}/mcp`, 'get_products', { adcp_version: preview, ...brief }); for (const pin of [{ adcp_version: '3.2' }, { adcp_version: '3.1' }, { adcp_version: '3.0' }, { adcp_major_version: 3 }, {}]) { @@ -500,7 +496,9 @@ describe('served-release response shape below 3.3 (#8487)', () => { const previewListing = await rpc(sales, rpcId += 1, 'tools/list', { _meta: { adcp_version: preview } }); const previewTools = (previewListing.result as { tools: Array<{ name: string; inputSchema?: { properties?: Record } }> }).tools; expect(previewTools.map(tool => tool.name)).toContain('list_collections'); - expect(previewTools.find(tool => tool.name === 'get_products')?.inputSchema?.properties).toHaveProperty('include_collections'); + // include_collections is withdrawn from get_products at every release and stays on list_products. + expect(previewTools.find(tool => tool.name === 'get_products')?.inputSchema?.properties).not.toHaveProperty('include_collections'); + expect(previewTools.find(tool => tool.name === 'list_products')?.inputSchema?.properties).toHaveProperty('include_collections'); }, 120_000); it('answers /mcp search_brands without a query with the correctable error the request schema requires', async () => { diff --git a/server/tests/unit/assignment-operations.test.ts b/server/tests/unit/assignment-operations.test.ts index 6ffe26515fd..84bb9e357ef 100644 --- a/server/tests/unit/assignment-operations.test.ts +++ b/server/tests/unit/assignment-operations.test.ts @@ -107,6 +107,23 @@ describe('sync_creatives assignment_operations', () => { }); }); + it.each([ + ['trackers', { trackers: [tracker] }], + ['landing_page_url', { landing_page_url: 'https://assign-ops.example/spring' }], + ])('rejects %s on a deprecated assignments[] row with INVALID_REQUEST (adcp#8501)', async (field, extra) => { + const server = createTrainingAgentServer(CTX); + const { mediaBuyId, packageId } = await buyWithPackage(server); + const result = await call(server, 'sync_creatives', { + account: ACCOUNT, + creatives: [creative('hero_v1')], + assignments: [{ creative_id: 'hero_v1', package_id: packageId, ...extra }], + }); + const error = result.errors?.[0] ?? result; + expect(error, JSON.stringify(result)).toMatchObject({ code: 'INVALID_REQUEST', field: `assignments[0].${field}` }); + // Nothing was assigned. + expect(await approvals(server, mediaBuyId)).toEqual([]); + }); + it('replace transfers trackers and the landing page, and advances the buy revision once', async () => { const server = createTrainingAgentServer(CTX); const { mediaBuyId, packageId } = await buyWithPackage(server); diff --git a/server/tests/unit/training-agent-collections.test.ts b/server/tests/unit/training-agent-collections.test.ts index 2c3222092bb..16aaba610fb 100644 --- a/server/tests/unit/training-agent-collections.test.ts +++ b/server/tests/unit/training-agent-collections.test.ts @@ -219,7 +219,7 @@ describe('experimental 3.3 collections on the training agent', () => { expect(creators.filter(card => card.distribution.length > 1).length).toBe(2); }, 60_000); - it('answers include_collections on all four product and proposal reads with the referenced cards only', async () => { + it('answers include_collections on list_products, request_proposals and refine_proposals with the referenced cards only, and never on get_products (adcp#8501)', async () => { const catalog = new Map((await listAll()).cards.map(card => [keyOf(card), card])); const checkCards = (label: string, result: Structured) => { expect(result.adcp_error, `${label}: ${JSON.stringify(result).slice(0, 400)}`).toBeUndefined(); @@ -239,8 +239,10 @@ describe('experimental 3.3 collections on the training agent', () => { }; const brief = 'Creator sponsored video integrations for an everyday lifestyle audience'; + // get_products no longer returns collections, even when asked, but keeps the sample_content projection. const gp = await preview('get_products', { buying_mode: 'brief', brief, include_collections: true }); - checkCards('get_products', gp); + expect(gp.adcp_error, JSON.stringify(gp).slice(0, 400)).toBeUndefined(); + expect(gp.collections).toBeUndefined(); const creatorProduct = (gp.products as Array>).find(product => (product.collections ?? []) .some((selector: { publisher_domain: string }) => selector.publisher_domain === CREATORS)); expect(creatorProduct).toBeDefined(); @@ -249,7 +251,7 @@ describe('experimental 3.3 collections on the training agent', () => { .filter((asset: { role: string }) => asset.role === 'sample_content'); expect(samples.length).toBeGreaterThan(0); expect(samples[0].asset).toMatchObject({ asset_type: 'url' }); - const card = (gp.collections as Card[]).find(entry => entry.collection_id === creatorProduct!.collections[0].collection_ids[0]); + const card = catalog.get(`${CREATORS}/${creatorProduct!.collections[0].collection_ids[0]}`); expect(card!.sample_content.map((post: { post_url: string }) => post.post_url)).toContain(samples[0].asset.url); const lp = await preview('list_products', { include_collections: true }); @@ -276,7 +278,7 @@ describe('experimental 3.3 collections on the training agent', () => { for (const [name, args] of [ ['get_products', { buying_mode: 'brief', brief }], ['list_products', {}], - ['get_products', { buying_mode: 'brief', brief, include_collections: false }], + ['list_products', { include_collections: false }], ] as const) { const plain = await preview(name, args); expect(plain.collections, name).toBeUndefined(); @@ -301,11 +303,7 @@ describe('experimental 3.3 collections on the training agent', () => { .flatMap(entry => entry.collections); expect(sellerAuthorized.length).toBeGreaterThan(0); - const gp = await preview('get_products', { - buying_mode: 'brief', - brief: 'Creator sponsored video integrations for an everyday lifestyle audience', - include_collections: true, - }); + const gp = await preview('list_products', { include_collections: true }); const keys = [...referencedKeys(gp.products)].map(key => { const [publisher_domain, collection_id] = key.split('/'); return { publisher_domain, collection_id }; @@ -408,10 +406,13 @@ describe('experimental 3.3 collections on the training agent', () => { expect((await preview('list_products', { include_collections: true, if_feed_version: plain.feed_version })).outcome).toBe('listed'); expect((await preview('list_products', { if_feed_version: withCards.feed_version })).outcome).toBe('listed'); + // get_products ignores include_collections (adcp#8501): same scope, same unsuffixed version. const gpPlain = await preview('get_products', { buying_mode: 'wholesale' }); const gpCards = await preview('get_products', { buying_mode: 'wholesale', include_collections: true }); - expect(gpCards.wholesale_feed_version).not.toBe(gpPlain.wholesale_feed_version); - expect((await preview('get_products', { buying_mode: 'wholesale', include_collections: true, if_wholesale_feed_version: gpCards.wholesale_feed_version })).unchanged).toBe(true); + expect(gpCards.wholesale_feed_version).toBe(gpPlain.wholesale_feed_version); + expect(gpCards.wholesale_feed_version).not.toMatch(/cards/); + expect(gpCards.collections).toBeUndefined(); + expect((await preview('get_products', { buying_mode: 'wholesale', include_collections: true, if_wholesale_feed_version: gpPlain.wholesale_feed_version })).unchanged).toBe(true); // A card change moves the card scope only. const changed = await seed({ diff --git a/server/tests/unit/training-agent-package-forecast.test.ts b/server/tests/unit/training-agent-package-forecast.test.ts deleted file mode 100644 index cfc5c14a1aa..00000000000 --- a/server/tests/unit/training-agent-package-forecast.test.ts +++ /dev/null @@ -1,148 +0,0 @@ -import { randomUUID } from 'node:crypto'; -import { beforeEach, describe, expect, it, vi } from 'vitest'; - -vi.hoisted(() => { - process.env.ADCP_STORYBOARD_CANDIDATE_VERSION_MODE = '1'; - process.env.ADCP_TRAINING_CANDIDATE_VERSION = '3.3-beta.1'; -}); - -import { - clearTaskStore, - executeTrainingAgentTool, - invalidateCache, -} from '../../src/training-agent/task-handlers.js'; -import { - clearSessions, - findSessionsMatching, - flushDirtySessions, - runWithSessionContext, -} from '../../src/training-agent/state.js'; -import { clearIdempotencyCache } from '../../src/training-agent/idempotency.js'; -import type { TrainingContext } from '../../src/training-agent/types.js'; - -const CTX: TrainingContext = { mode: 'open', principal: 'package-forecast-buyer' }; -const ACCOUNT = { brand: { domain: 'nova-motors.example' }, operator: 'forecast-buyer', sandbox: true }; -const HORIZON = { start_time: '2099-11-01T00:00:00Z', end_time: '2099-12-01T00:00:00Z' }; -const PRODUCT_ID = 'streamhaus_forecast_product'; - -const call = (toolName: string, args: Record) => runWithSessionContext(async () => { - const result = await executeTrainingAgentTool(toolName, { - adcp_version: '3.3-beta.1', - idempotency_key: randomUUID(), - account: ACCOUNT, - ...args, - }, CTX); - await flushDirtySessions(); - return result; -}); - -const packageInput = () => ({ - pricing_option_id: 'fixture_default_cpm', - budget: 25000, - start_time: HORIZON.start_time, - end_time: HORIZON.end_time, - targeting_overlay: {}, -}); - -describe('structured package forecasts on the reference training agent', () => { - beforeEach(async () => { - await clearSessions(); - clearIdempotencyCache(); - invalidateCache(); - clearTaskStore(); - const seed = await call('comply_test_controller', { - scenario: 'seed_product', - params: { - product_id: PRODUCT_ID, - fixture: { - delivery_type: 'guaranteed', - channels: ['display'], - availability: { min_bookable_days: 1, booked_windows: [] }, - }, - }, - }); - expect(seed).toMatchObject({ success: true, data: { success: true } }); - }); - - it('reports unable and suppresses even a later horizon forecast without booking or reserving inventory', async () => { - const discovery = await call('get_products', { - buying_mode: 'wholesale', - filters: { availability_horizon: HORIZON }, - }); - const baseline = (discovery.data as { products: Array> }).products - .find(product => product.product_id === PRODUCT_ID); - expect(baseline?.forecast).toMatchObject({ forecast_range_unit: 'availability' }); - - const result = await call('get_products', { - buying_mode: 'refine', - filters: { availability_horizon: HORIZON }, - refine: [{ scope: 'product', product_id: PRODUCT_ID, package: packageInput() }], - }); - expect(result.success).toBe(true); - const data = result.data as { - adcp_version: string; - products: Array>; - refinement_applied: Array>; - }; - expect(data.adcp_version).toBe('3.3-beta.1'); - expect(data.refinement_applied).toEqual([{ - scope: 'product', product_id: PRODUCT_ID, status: 'unable', notes: expect.stringMatching(/\S/), - }]); - const returnedProduct = data.products.find(product => product.product_id === PRODUCT_ID); - expect(returnedProduct).toMatchObject({ product_id: PRODUCT_ID }); - expect(returnedProduct).not.toHaveProperty('forecast'); - - const sessions = await findSessionsMatching(() => true); - expect(sessions.length).toBeGreaterThan(0); - for (const session of sessions) { - expect(session.mediaBuys.size).toBe(0); - expect(session.creatives.size).toBe(0); - expect(session.negotiatedPricingOptions.size).toBe(0); - expect(session.lastGetProductsContext?.proposals?.some(proposal => proposal.proposal_status === 'committed')).not.toBe(true); - } - - const ordinary = await call('get_products', { - buying_mode: 'refine', - filters: { availability_horizon: HORIZON }, - refine: [{ scope: 'product', product_id: PRODUCT_ID }], - }); - expect((ordinary.data as { refinement_applied: Array> }).refinement_applied) - .toEqual([{ scope: 'product', product_id: PRODUCT_ID, status: 'applied' }]); - expect((ordinary.data as { products: Array> }).products - .find(product => product.product_id === PRODUCT_ID)?.forecast) - .toMatchObject({ forecast_range_unit: 'availability' }); - }); - - it('keeps all outcomes aligned and does not reprice an unsupported package from its free-text ask', async () => { - const result = await call('get_products', { - buying_mode: 'refine', - refine: [ - { scope: 'request', ask: 'Keep the selected product' }, - { scope: 'product', product_id: PRODUCT_ID, action: 'include', package: packageInput(), ask: 'Set the CPM to USD 5' }, - ], - }); - expect(result.success).toBe(true); - const data = result.data as { products: Array>; refinement_applied: Array> }; - expect(data.refinement_applied).toHaveLength(2); - expect(data.refinement_applied[0]).toMatchObject({ scope: 'request' }); - expect(data.refinement_applied[1]).toMatchObject({ scope: 'product', product_id: PRODUCT_ID, status: 'unable' }); - const returnedProduct = data.products.find(product => product.product_id === PRODUCT_ID); - expect(returnedProduct).toMatchObject({ product_id: PRODUCT_ID }); - expect(returnedProduct).not.toHaveProperty('forecast'); - for (const session of await findSessionsMatching(() => true)) { - expect(session.negotiatedPricingOptions.size).toBe(0); - } - }); - - it.each([ - { action: 'omit', package: packageInput() }, - { package: { ...packageInput(), budget: -1 } }, - ])('rejects an invalid structured package before treating it as ordinary refinement', async entry => { - const result = await call('get_products', { - buying_mode: 'refine', - refine: [{ scope: 'product', product_id: PRODUCT_ID, ...entry }], - }); - expect(result.success).toBe(false); - expect(result.error).toMatch(/Invalid get_products_request/); - }); -}); diff --git a/static/compliance/source/protocols/media-buy/scenarios/execution_readiness.yaml b/static/compliance/source/protocols/media-buy/scenarios/execution_readiness.yaml index 8fca1addf36..25b5a3ef542 100644 --- a/static/compliance/source/protocols/media-buy/scenarios/execution_readiness.yaml +++ b/static/compliance/source/protocols/media-buy/scenarios/execution_readiness.yaml @@ -15,7 +15,7 @@ requires_capability: required_tools: - get_adcp_capabilities - - get_products + - list_products - sync_accounts - sync_event_sources - comply_test_controller @@ -23,11 +23,11 @@ required_tools: narrative: | A wholesale catalogue is the same for every buyer, but whether an account can run a product depends on what that account has: a conversion product needs an - event source, and the buyer needs to know before calling create_media_buy - whether the account has none, one, or several to choose from. + event source, and the buyer needs to know before buying whether the account + has none, one, or several to choose from. The seller reports this in a response-level `execution_readiness` map keyed by - product_id. This scenario exercises the four states a buyer agent has to tell + product_id on list_products. This scenario exercises the four states a buyer agent has to tell apart: ready by a unique candidate, setup required when the account has none, selection required when it has several, and unknown when the seller cannot read the account. Unknown MUST NOT be reported as setup_required, because the @@ -156,19 +156,18 @@ phases: - id: read_ready title: "Read readiness for the account with one event source" - task: get_products - schema_ref: "media-buy/get-products-request.json" - response_schema_ref: "media-buy/get-products-response.json" - doc_ref: "/media-buy/task-reference/get_products" + task: list_products + schema_ref: "media-buy/list-products-request.json" + response_schema_ref: "media-buy/list-products-response.json" + doc_ref: "/media-buy/task-reference/list_products" stateful: false expected: | Return the product with execution_readiness.products status ready and the requirement resolved to the registered event source. sample_request: - buying_mode: "wholesale" include_execution_readiness: true - filters: - pricing_currencies: ["USD"] + criteria: + product_ids: ["execution_readiness_conversions"] account: brand: domain: "readiness-ready.example" @@ -176,7 +175,7 @@ phases: sandbox: true validations: - check: response_schema - description: "Response matches get-products-response.json schema" + description: "Response matches list-products-response.json schema" - check: field_value path: "cache_scope" value: "public" @@ -198,17 +197,16 @@ phases: - id: omit_without_opt_in title: "Omit the map unless the buyer opts in" - task: get_products - schema_ref: "media-buy/get-products-request.json" - response_schema_ref: "media-buy/get-products-response.json" - doc_ref: "/media-buy/task-reference/get_products" + task: list_products + schema_ref: "media-buy/list-products-request.json" + response_schema_ref: "media-buy/list-products-response.json" + doc_ref: "/media-buy/task-reference/list_products" stateful: false expected: | Return products without an execution_readiness map. sample_request: - buying_mode: "wholesale" - filters: - pricing_currencies: ["USD"] + criteria: + product_ids: ["execution_readiness_conversions"] account: brand: domain: "readiness-ready.example" @@ -216,7 +214,7 @@ phases: sandbox: true validations: - check: response_schema - description: "Response matches get-products-response.json schema" + description: "Response matches list-products-response.json schema" - check: field_absent path: "execution_readiness" description: "Readiness is opt-in" @@ -226,18 +224,17 @@ phases: steps: - id: read_setup_required title: "Read readiness for the account with no event source" - task: get_products - schema_ref: "media-buy/get-products-request.json" - response_schema_ref: "media-buy/get-products-response.json" - doc_ref: "/media-buy/task-reference/get_products" + task: list_products + schema_ref: "media-buy/list-products-request.json" + response_schema_ref: "media-buy/list-products-response.json" + doc_ref: "/media-buy/task-reference/list_products" stateful: false expected: | Return the product, annotated setup_required rather than omitted. sample_request: - buying_mode: "wholesale" include_execution_readiness: true - filters: - pricing_currencies: ["USD"] + criteria: + product_ids: ["execution_readiness_conversions"] account: brand: domain: "readiness-setup.example" @@ -245,7 +242,7 @@ phases: sandbox: true validations: - check: response_schema - description: "Response matches get-products-response.json schema" + description: "Response matches list-products-response.json schema" - check: field_contains path: "products[*].product_id" value: "execution_readiness_conversions" @@ -294,19 +291,18 @@ phases: - id: read_selection_required title: "Read readiness for the account with two event sources" - task: get_products - schema_ref: "media-buy/get-products-request.json" - response_schema_ref: "media-buy/get-products-response.json" - doc_ref: "/media-buy/task-reference/get_products" + task: list_products + schema_ref: "media-buy/list-products-request.json" + response_schema_ref: "media-buy/list-products-response.json" + doc_ref: "/media-buy/task-reference/list_products" stateful: false expected: | Return the product as selection_required with both event sources as candidates the buyer can bind directly. sample_request: - buying_mode: "wholesale" include_execution_readiness: true - filters: - pricing_currencies: ["USD"] + criteria: + product_ids: ["execution_readiness_conversions"] account: brand: domain: "readiness-select.example" @@ -314,7 +310,7 @@ phases: sandbox: true validations: - check: response_schema - description: "Response matches get-products-response.json schema" + description: "Response matches list-products-response.json schema" - check: field_value path: "execution_readiness.products.execution_readiness_conversions.readiness_status" value: "selection_required" @@ -340,19 +336,18 @@ phases: steps: - id: read_unknown title: "Read readiness for the unreadable account" - task: get_products - schema_ref: "media-buy/get-products-request.json" - response_schema_ref: "media-buy/get-products-response.json" - doc_ref: "/media-buy/task-reference/get_products" + task: list_products + schema_ref: "media-buy/list-products-request.json" + response_schema_ref: "media-buy/list-products-response.json" + doc_ref: "/media-buy/task-reference/list_products" stateful: false expected: | Return the product, annotated unknown with unknown_reason permission_denied and no resolved resource or candidates. sample_request: - buying_mode: "wholesale" include_execution_readiness: true - filters: - pricing_currencies: ["USD"] + criteria: + product_ids: ["execution_readiness_conversions"] account: brand: domain: "readiness-unreadable.example" @@ -360,7 +355,7 @@ phases: sandbox: true validations: - check: response_schema - description: "Response matches get-products-response.json schema" + description: "Response matches list-products-response.json schema" - check: field_contains path: "products[*].product_id" value: "execution_readiness_conversions" diff --git a/static/compliance/source/test-vectors/price-adjustments/README.md b/static/compliance/source/test-vectors/price-adjustments/README.md deleted file mode 100644 index 3ff59adf194..00000000000 --- a/static/compliance/source/test-vectors/price-adjustments/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# Price adjustment resolution vectors - -These vectors pin the deterministic resolution rule for `price_adjustments` on -a binding fixed-price pricing option. A table is optional: a fully priced offer -is an equally supported path, and its price applies only to what was quoted. - -1. **One running total, declared order.** Starting at `fixed_price`, each - firing row applies to the running total in the seller's declared order. A - `rate` row adds (`fee`) or subtracts (`discount`) `round(running x rate)`; an - `amount` row adds or subtracts its amount, and later rate rows apply to the - total including it. A 10% fee then a 10% fee is x1.21, not x1.20. -2. **Index cards are rates.** There is no separate index row kind: a factor - `f > 1` is a fee `rate` of `f - 1` and a factor `f < 1` is a discount `rate` - of `1 - f`, applied in the same sequence. A fee `rate` may be 1 or more - (factor 2.5 is a fee rate of 1.5). -3. Selection rows (`format_option`, `placement_selection`) fire at most once per - dimension: the first applicable row in declared order. `always` rows each - fire. Matching is full-identity equality after resolution. -4. `valid_from` (inclusive) / `valid_until` (exclusive) bound a row to a window - evaluated at the purchase `start_time`. A flight that crosses a window - boundary of a row that would otherwise apply is rejected with - `INVALID_REQUEST`; a flight may end exactly on a `valid_until`. -5. Every delta rounds half away from zero to the option's price precision: the - greatest of the currency minor-unit exponent, 4 for - `cpm`/`vcpm`/`cpc`/`cpcv`/`cpv`/`cpp`, and the fewest decimal places that - exactly represent `fixed_price` and each amount, by numeric value. The - resolved price is the exact running total and never falls below zero. -6. Omitted or default selections match no selection row and pay the base rate. -7. A buyer-supplied `pricing` that differs from the resolved result is rejected - with `INVALID_REQUEST` carrying the resolved price and breakdown; a changed - table requires a new `pricing_option_id`. -8. An accepted snapshot carries the resolved `fixed_price` and a - `price_breakdown` of the declared adjustments plus each fired row in declared - order (a rate below 1 as its rate, otherwise as its currency amount), both - existing fields, so a verifier can re-resolve it. The table is not embedded - in the snapshot (the canonical schemas are closed; embedding is a 4.0 item, - #8501). -9. **Quotes stay bound to their terms** (`quote_binding_cases`). A table applies - only to the account it was returned for and expires with the quote: the - proposal or offer `expires_at`, or the discovery response's validity. -10. **Accepted terms** (`accepted_terms_cases`). A changed table is a new - `pricing_option_id`, so the accepted `pricing_option_id` (covered by - `terms_digest`) identifies exactly one immutable table, which both parties - retain from discovery. A change the agreement already permits is priced from - that table, never from a later table, without a re-quote. The table grants no - change right: a change not permitted by `change_terms[]` is - `ACTION_NOT_ALLOWED` whatever the table says. - -The `dutch_tv_*` cases are a fictional linear TV rate card: a net base price -multiplied by month, market, spot-length and target-audience indices (written as -fee and discount rates), plus a first-in-break premium. Resolvers MUST use exact -decimal or integer arithmetic; the tie cases fail under binary floating point or -currency-only rounding. SDK suites consume this file to check their own -resolvers. diff --git a/static/compliance/source/test-vectors/price-adjustments/vectors.json b/static/compliance/source/test-vectors/price-adjustments/vectors.json deleted file mode 100644 index c73649defff..00000000000 --- a/static/compliance/source/test-vectors/price-adjustments/vectors.json +++ /dev/null @@ -1,1809 +0,0 @@ -{ - "description": "Deterministic resolution vectors for price_adjustments on binding fixed-price pricing options. One running total: starting at fixed_price, each firing row applies to it in declared order (a rate row adds or subtracts round half away from zero of running x rate, an amount row adds or subtracts its amount), so a 10% fee then a 10% fee is x1.21. Dutch index cards are expressed as fee or discount rates (factor 1.25 is a fee rate of 0.25, factor 0.80 a discount rate of 0.20). Selection rows fire at most once per dimension (the first valid matching row in declared order); always rows fire independently; valid_from/valid_until bound a row to a half-open window evaluated at the purchase start_time, and a flight that crosses a window boundary of a row that would otherwise apply is rejected. Price precision is the greatest of the currency minor-unit exponent, 4 for cpm/vcpm/cpc/cpcv/cpv/cpp, and the fewest decimals that exactly represent fixed_price and each amount, by numeric value; the resolved price is the exact running total and never below zero. Arithmetic MUST be exact decimal or integer. Each fired row is recorded in price_breakdown in declared order: a rate below 1 as its rate, otherwise (a fee rate of 1 or more, or an amount row) as its currency amount. A table is bound to its quote: it applies only to the account it was returned for and until the quote expires. A changed table is a new pricing_option_id, so the accepted pricing_option_id identifies exactly one immutable table, which both parties retain from discovery; a change the agreement already permits is priced from that table, never a later one, and the table grants no change right.", - "currency_minor_unit_exponent": { - "USD": 2, - "JPY": 0, - "EUR": 2 - }, - "options": { - "cpm_rate_card": { - "pricing_option_id": "cpm_usd_rate_card_v1", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_sports" - }, - "kind": "fee", - "name": "premium_sports_placement", - "rate": 0.1 - } - ] - }, - "cpm_placement_first": { - "pricing_option_id": "cpm_usd_rate_card_v2", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - }, - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - }, - "cpm_two_dimension_rates": { - "pricing_option_id": "cpm_usd_two_rates", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 10.0, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "rate": 0.1 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.1 - } - ] - }, - "cpm_rounding": { - "pricing_option_id": "cpm_usd_rounding", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 1.15, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "rate": 0.001 - } - ] - }, - "cpm_deep_discount": { - "pricing_option_id": "cpm_usd_deep_discount", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 1.0, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "discount", - "name": "launch_credit", - "amount": 2.0 - } - ] - }, - "cpm_declared_breakdown": { - "pricing_option_id": "cpm_usd_negotiated_v1", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_breakdown": { - "list_price": 25.0, - "adjustments": [ - { - "kind": "discount", - "name": "volume", - "rate": 0.2 - } - ] - }, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - }, - "cpm_publisher_format": { - "pricing_option_id": "cpm_usd_publisher_format", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 10.0, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "publisher", - "publisher_domain": "streamhaus.example", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "publisher_video_30s", - "amount": 1.0 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "amount": 0.5 - } - ] - }, - "cpv_sub_cent": { - "pricing_option_id": "cpv_usd_sub_cent", - "pricing_model": "cpv", - "currency": "USD", - "fixed_price": 0.0125, - "parameters": { - "view_threshold": 0.5 - }, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "rate": 0.05 - } - ] - }, - "flat_jpy": { - "pricing_option_id": "flat_jpy_rate_card", - "pricing_model": "flat_rate", - "currency": "JPY", - "fixed_price": 1000, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "rate": 0.0005 - } - ] - }, - "cpv_five_decimals": { - "pricing_option_id": "cpv_usd_five_decimals", - "pricing_model": "cpv", - "currency": "USD", - "fixed_price": 0.00125, - "parameters": { - "view_threshold": 0.5 - }, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "rate": 0.1 - } - ] - }, - "tv_grp_rate_card": { - "pricing_option_id": "oranje_grp_eur_2026", - "pricing_model": "cpp", - "currency": "EUR", - "fixed_price": 1000, - "parameters": { - "demographic": "A25-54" - }, - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "month_index_nov", - "rate": 0.1, - "valid_from": "2026-11-01T00:00:00+01:00", - "valid_until": "2026-12-01T00:00:00+01:00" - }, - { - "dimension": "always", - "kind": "discount", - "name": "market_index_nov", - "rate": 0.05, - "valid_from": "2026-11-01T00:00:00+01:00", - "valid_until": "2026-12-01T00:00:00+01:00" - }, - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "spot_20s" - }, - "kind": "discount", - "name": "spot_length_20s", - "rate": 0.2 - }, - { - "dimension": "always", - "kind": "fee", - "name": "target_audience_a25_54", - "rate": 0.25 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "oranjetv.example", - "placement_id": "first_in_break" - }, - "kind": "fee", - "name": "first_in_break_premium", - "rate": 0.2 - } - ] - }, - "cpm_index_then_premium": { - "pricing_option_id": "cpm_usd_index_premium", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "season_index", - "rate": 0.1 - }, - { - "dimension": "placement_selection", - "placement_ref": { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - }, - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - }, - "cpm_two_indices": { - "pricing_option_id": "cpm_usd_two_indices", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "season_index", - "rate": 0.1 - }, - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "length_index", - "rate": 0.2 - } - ] - }, - "cpm_index_rounding": { - "pricing_option_id": "cpm_usd_index_rounding", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 1.2345, - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "season_index", - "rate": 0.1 - } - ] - }, - "cpm_index_below_one": { - "pricing_option_id": "cpm_usd_index_below_one", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "always", - "kind": "discount", - "name": "off_peak_index", - "rate": 0.15 - } - ] - }, - "cpm_windowed_alternates": { - "pricing_option_id": "cpm_usd_windowed_alternates", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "length_index_nov", - "rate": 0.1, - "valid_from": "2026-11-01T00:00:00+01:00", - "valid_until": "2026-12-01T00:00:00+01:00" - }, - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "length_index_dec", - "rate": 0.2, - "valid_from": "2026-12-01T00:00:00+01:00", - "valid_until": "2027-01-01T00:00:00+01:00" - } - ] - }, - "cpm_prime_index": { - "pricing_option_id": "cpm_usd_prime_index", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "prime_position_index", - "rate": 1.5 - } - ] - }, - "cpm_two_fees": { - "pricing_option_id": "cpm_usd_two_fees", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 100.0, - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "platform_fee", - "rate": 0.1 - }, - { - "dimension": "always", - "kind": "fee", - "name": "cover_fee", - "rate": 0.1 - } - ] - }, - "cpm_seller_inline_placement": { - "pricing_option_id": "cpm_usd_seller_inline", - "pricing_model": "cpm", - "currency": "USD", - "fixed_price": 20.0, - "price_adjustments": [ - { - "dimension": "placement_selection", - "placement_ref": { - "kind": "seller_inline", - "seller_agent": { - "agent_url": "https://Agent.Example:443/" - }, - "placement_id": "premium_home" - }, - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - } - }, - "resolution_cases": [ - { - "id": "one_adjustment", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 22.0, - "applied": [ - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - } - }, - { - "id": "amount_then_rate_applies_to_running_total", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 25.3, - "applied": [ - "video_30s_format", - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - }, - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - } - }, - { - "id": "declared_order_changes_the_price", - "option": "cpm_placement_first", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 25.0, - "applied": [ - "premium_home_placement", - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - }, - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - } - }, - { - "id": "unmatched_selection_pays_base_rate", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "display_300x250" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "run_of_site" - } - ] - } - }, - "expect": { - "fixed_price": 20.0, - "applied": [], - "breakdown": [] - } - }, - { - "id": "default_selection_matches_no_row", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 20.0, - "applied": [], - "breakdown": [] - } - }, - { - "id": "multi_value_dimension_fires_first_matching_row_once", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_sports" - }, - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 23.0, - "applied": [ - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - } - }, - { - "id": "two_ten_percent_fees_compound_to_twenty_one_percent", - "option": "cpm_two_fees", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 121.0, - "applied": [ - "platform_fee", - "cover_fee" - ], - "breakdown": [ - { - "kind": "fee", - "name": "platform_fee", - "rate": 0.1 - }, - { - "kind": "fee", - "name": "cover_fee", - "rate": 0.1 - } - ] - } - }, - { - "id": "rates_across_dimensions_compound", - "option": "cpm_two_dimension_rates", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 12.1, - "applied": [ - "video_30s_format", - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "rate": 0.1 - }, - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.1 - } - ] - } - }, - { - "id": "rate_delta_rounds_half_away_from_zero_to_price_precision", - "option": "cpm_rounding", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 1.1512, - "applied": [ - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "rate": 0.001 - } - ] - } - }, - { - "id": "surcharges_apply_to_net_of_declared_breakdown", - "option": "cpm_declared_breakdown", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 25.3, - "applied": [ - "video_30s_format", - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - }, - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - } - }, - { - "id": "declared_breakdown_with_amount_row_only", - "option": "cpm_declared_breakdown", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 22.0, - "applied": [ - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - } - }, - { - "id": "sub_cent_unit_price_keeps_four_decimals", - "option": "cpv_sub_cent", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 0.0131, - "applied": [ - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "rate": 0.05 - } - ] - } - }, - { - "id": "declared_five_decimals_set_price_precision", - "option": "cpv_five_decimals", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 0.00138, - "applied": [ - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "rate": 0.1 - } - ] - } - }, - { - "id": "flat_rate_zero_exponent_currency_rounds_to_whole_units", - "option": "flat_jpy", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 1001, - "applied": [ - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "rate": 0.0005 - } - ] - } - }, - { - "id": "legacy_and_identity_placement_encodings_match", - "option": "cpm_publisher_format", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "kind": "publisher_ref", - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 10.5, - "applied": [ - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "premium_home_placement", - "amount": 0.5 - } - ] - } - }, - { - "id": "seller_inline_agent_url_matches_under_url_canonicalization", - "option": "cpm_seller_inline_placement", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "kind": "seller_inline", - "seller_agent": { - "agent_url": "https://agent.example/" - }, - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 23.0, - "applied": [ - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - } - }, - { - "id": "seller_inline_different_agent_does_not_match", - "option": "cpm_seller_inline_placement", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "kind": "seller_inline", - "seller_agent": { - "agent_url": "https://other.example/" - }, - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 20.0, - "applied": [], - "breakdown": [] - } - }, - { - "id": "same_format_id_under_different_scope_does_not_match", - "option": "cpm_publisher_format", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 10.0, - "applied": [], - "breakdown": [] - } - }, - { - "id": "publisher_scoped_format_matches_publisher_scoped_row", - "option": "cpm_publisher_format", - "selection": { - "format_option_refs": [ - { - "scope": "publisher", - "publisher_domain": "streamhaus.example", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 11.0, - "applied": [ - "publisher_video_30s" - ], - "breakdown": [ - { - "kind": "fee", - "name": "publisher_video_30s", - "amount": 1.0 - } - ] - } - }, - { - "id": "dutch_tv_index_stack_then_first_in_break_premium", - "option": "tv_grp_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "spot_20s" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "oranjetv.example", - "placement_id": "first_in_break" - } - ] - }, - "flight": { - "start_time": "2026-11-09T00:00:00+01:00", - "end_time": "2026-11-22T00:00:00+01:00" - } - }, - "expect": { - "fixed_price": 1254.0, - "applied": [ - "month_index_nov", - "market_index_nov", - "spot_length_20s", - "target_audience_a25_54", - "first_in_break_premium" - ], - "breakdown": [ - { - "kind": "fee", - "name": "month_index_nov", - "rate": 0.1 - }, - { - "kind": "discount", - "name": "market_index_nov", - "rate": 0.05 - }, - { - "kind": "discount", - "name": "spot_length_20s", - "rate": 0.2 - }, - { - "kind": "fee", - "name": "target_audience_a25_54", - "rate": 0.25 - }, - { - "kind": "fee", - "name": "first_in_break_premium", - "rate": 0.2 - } - ] - } - }, - { - "id": "dutch_tv_month_windows_do_not_apply_in_december", - "option": "tv_grp_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "spot_20s" - } - ], - "placement_selection": { - "mode": "default" - }, - "flight": { - "start_time": "2026-12-07T00:00:00+01:00", - "end_time": "2026-12-20T00:00:00+01:00" - } - }, - "expect": { - "fixed_price": 1000.0, - "applied": [ - "spot_length_20s", - "target_audience_a25_54" - ], - "breakdown": [ - { - "kind": "discount", - "name": "spot_length_20s", - "rate": 0.2 - }, - { - "kind": "fee", - "name": "target_audience_a25_54", - "rate": 0.25 - } - ] - } - }, - { - "id": "window_end_is_exclusive_and_flight_may_end_on_it", - "option": "tv_grp_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "spot_20s" - } - ], - "placement_selection": { - "mode": "default" - }, - "flight": { - "start_time": "2026-11-23T00:00:00+01:00", - "end_time": "2026-12-01T00:00:00+01:00" - } - }, - "expect": { - "fixed_price": 1045.0, - "applied": [ - "month_index_nov", - "market_index_nov", - "spot_length_20s", - "target_audience_a25_54" - ], - "breakdown": [ - { - "kind": "fee", - "name": "month_index_nov", - "rate": 0.1 - }, - { - "kind": "discount", - "name": "market_index_nov", - "rate": 0.05 - }, - { - "kind": "discount", - "name": "spot_length_20s", - "rate": 0.2 - }, - { - "kind": "fee", - "name": "target_audience_a25_54", - "rate": 0.25 - } - ] - } - }, - { - "id": "window_start_at_valid_until_does_not_fire", - "option": "tv_grp_rate_card", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - }, - "flight": { - "start_time": "2026-12-01T00:00:00+01:00", - "end_time": "2026-12-14T00:00:00+01:00" - } - }, - "expect": { - "fixed_price": 1250.0, - "applied": [ - "target_audience_a25_54" - ], - "breakdown": [ - { - "kind": "fee", - "name": "target_audience_a25_54", - "rate": 0.25 - } - ] - } - }, - { - "id": "later_rate_applies_to_the_running_total_not_the_base", - "option": "cpm_index_then_premium", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "expect": { - "fixed_price": 25.3, - "applied": [ - "season_index", - "premium_home_placement" - ], - "breakdown": [ - { - "kind": "fee", - "name": "season_index", - "rate": 0.1 - }, - { - "kind": "fee", - "name": "premium_home_placement", - "rate": 0.15 - } - ] - } - }, - { - "id": "amount_after_a_rate_is_not_scaled_by_it", - "option": "cpm_index_then_premium", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 24.0, - "applied": [ - "season_index", - "video_30s_format" - ], - "breakdown": [ - { - "kind": "fee", - "name": "season_index", - "rate": 0.1 - }, - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - } - }, - { - "id": "index_card_rows_compound_in_declared_order", - "option": "cpm_two_indices", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 26.4, - "applied": [ - "season_index", - "length_index" - ], - "breakdown": [ - { - "kind": "fee", - "name": "season_index", - "rate": 0.1 - }, - { - "kind": "fee", - "name": "length_index", - "rate": 0.2 - } - ] - } - }, - { - "id": "index_card_row_rounds_half_away_from_zero_at_price_precision", - "option": "cpm_index_rounding", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 1.358, - "applied": [ - "season_index" - ], - "breakdown": [ - { - "kind": "fee", - "name": "season_index", - "rate": 0.1 - } - ] - } - }, - { - "id": "index_factor_below_one_is_a_discount_rate", - "option": "cpm_index_below_one", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 17.0, - "applied": [ - "off_peak_index" - ], - "breakdown": [ - { - "kind": "discount", - "name": "off_peak_index", - "rate": 0.15 - } - ] - } - }, - { - "id": "first_valid_row_per_dimension_picks_the_window", - "option": "cpm_windowed_alternates", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - }, - "flight": { - "start_time": "2026-12-07T00:00:00+01:00", - "end_time": "2026-12-20T00:00:00+01:00" - } - }, - "expect": { - "fixed_price": 24.0, - "applied": [ - "length_index_dec" - ], - "breakdown": [ - { - "kind": "fee", - "name": "length_index_dec", - "rate": 0.2 - } - ] - } - }, - { - "id": "fee_rate_of_one_or_more_is_recorded_as_its_currency_amount", - "option": "cpm_prime_index", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - } - }, - "expect": { - "fixed_price": 50.0, - "applied": [ - "prime_position_index" - ], - "breakdown": [ - { - "kind": "fee", - "name": "prime_position_index", - "amount": 30.0 - } - ] - } - } - ], - "invalid_resolution_cases": [ - { - "id": "discount_below_zero", - "option": "cpm_deep_discount", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "expect_error": "below_zero", - "expect_outcome": "INVALID_REQUEST" - }, - { - "id": "flight_crossing_a_window_boundary_is_rejected", - "option": "tv_grp_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "spot_20s" - } - ], - "placement_selection": { - "mode": "default" - }, - "flight": { - "start_time": "2026-11-25T00:00:00+01:00", - "end_time": "2026-12-05T00:00:00+01:00" - } - }, - "expect_error": "flight_spans_validity_boundary", - "expect_outcome": "INVALID_REQUEST" - }, - { - "id": "flight_starting_before_a_window_and_ending_inside_it_is_rejected", - "option": "tv_grp_rate_card", - "selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - }, - "flight": { - "start_time": "2026-10-28T00:00:00+01:00", - "end_time": "2026-11-05T00:00:00+01:00" - } - }, - "expect_error": "flight_spans_validity_boundary", - "expect_outcome": "INVALID_REQUEST" - } - ], - "buyer_supplied_pricing_cases": [ - { - "id": "matching_buyer_pricing_accepted", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "supplied_fixed_price": 22.0, - "expect": "accepted" - }, - { - "id": "base_rate_supplied_for_priced_selection_rejected", - "option": "cpm_rate_card", - "selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "supplied_fixed_price": 20.0, - "expect": "INVALID_REQUEST", - "error_field": "pricing.fixed_price", - "resolved_fixed_price": 22.0, - "resolved_breakdown": [ - { - "kind": "fee", - "name": "video_30s_format", - "amount": 2.0 - } - ] - } - ], - "identity_cases": [ - { - "id": "changed_table_requires_new_pricing_option_id", - "previous": "cpm_rate_card", - "current": "cpm_placement_first", - "expect": "distinct_pricing_option_ids" - } - ], - "schema_negative_cases": [ - { - "id": "rate_and_amount_together", - "mutate": { - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "fee", - "name": "both", - "rate": 0.1, - "amount": 1.0 - } - ] - } - }, - { - "id": "commission_kind_not_selection_dependent", - "mutate": { - "price_adjustments": [ - { - "dimension": "format_option", - "format_option_ref": { - "scope": "product", - "format_option_id": "video_30s" - }, - "kind": "commission", - "name": "agency", - "rate": 0.1 - } - ] - } - }, - { - "id": "property_list_dimension_not_priceable_in_v1", - "mutate": { - "price_adjustments": [ - { - "dimension": "property_list", - "kind": "fee", - "name": "premium_properties", - "rate": 0.1 - } - ] - } - }, - { - "id": "adjustments_require_fixed_price", - "mutate": { - "fixed_price": null, - "floor_price": 5.0 - } - }, - { - "id": "index_kind_is_not_defined", - "mutate": { - "price_adjustments": [ - { - "dimension": "always", - "kind": "index", - "name": "x", - "factor": 1.1 - } - ] - } - }, - { - "id": "validity_window_must_be_a_date_time", - "mutate": { - "price_adjustments": [ - { - "dimension": "always", - "kind": "index", - "name": "x", - "factor": 1.1, - "valid_from": "November" - } - ] - } - }, - { - "id": "factor_is_not_a_row_field", - "mutate": { - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "x", - "factor": 1.1 - } - ] - } - }, - { - "id": "rate_must_be_positive", - "mutate": { - "price_adjustments": [ - { - "dimension": "always", - "kind": "fee", - "name": "x", - "rate": 0 - } - ] - } - }, - { - "id": "collection_list_dimension_not_priceable_in_v1", - "mutate": { - "price_adjustments": [ - { - "dimension": "collection_list", - "kind": "fee", - "name": "premium_collections", - "rate": 0.1 - } - ] - } - } - ], - "quote_binding_cases": [ - { - "id": "table_applies_to_the_quoted_account_before_expiry", - "quote": { - "account_id": "acct_nova", - "expires_at": "2026-11-01T00:00:00Z" - }, - "use": { - "account_id": "acct_nova", - "at": "2026-10-31T23:59:59Z" - }, - "expect": "table_applies" - }, - { - "id": "table_does_not_apply_to_another_account", - "quote": { - "account_id": "acct_nova", - "expires_at": "2026-11-01T00:00:00Z" - }, - "use": { - "account_id": "acct_pinnacle", - "at": "2026-10-30T00:00:00Z" - }, - "expect": "table_does_not_apply" - }, - { - "id": "table_expires_with_the_quote", - "quote": { - "account_id": "acct_nova", - "expires_at": "2026-11-01T00:00:00Z" - }, - "use": { - "account_id": "acct_nova", - "at": "2026-11-01T00:00:00Z" - }, - "expect": "table_does_not_apply" - } - ], - "accepted_terms_cases": [ - { - "id": "permitted_change_is_priced_from_the_accepted_options_table_without_a_requote", - "option": "cpm_rate_card", - "accepted_selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "requested_selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "change_permitted_by_change_terms": true, - "expect": { - "outcome": "priced", - "fixed_price": 23.0 - } - }, - { - "id": "table_grants_no_change_right", - "option": "cpm_rate_card", - "accepted_selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "requested_selection": { - "format_option_refs": [], - "placement_selection": { - "mode": "default" - } - }, - "change_permitted_by_change_terms": false, - "expect": { - "outcome": "ACTION_NOT_ALLOWED" - } - }, - { - "id": "later_table_does_not_reprice_the_accepted_option", - "option": "cpm_rate_card", - "later_option": "cpm_placement_first", - "accepted_selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "default" - } - }, - "requested_selection": { - "format_option_refs": [ - { - "scope": "product", - "format_option_id": "video_30s" - } - ], - "placement_selection": { - "mode": "selected", - "placement_refs": [ - { - "publisher_domain": "streamhaus.example", - "placement_id": "premium_home" - } - ] - } - }, - "change_permitted_by_change_terms": true, - "expect": { - "outcome": "priced", - "fixed_price": 25.3 - } - } - ] -} diff --git a/static/compliance/source/universal/v4-compatibility.yaml b/static/compliance/source/universal/v4-compatibility.yaml index c84787f59e2..709552580e7 100644 --- a/static/compliance/source/universal/v4-compatibility.yaml +++ b/static/compliance/source/universal/v4-compatibility.yaml @@ -224,9 +224,12 @@ checks: Accept the experimental target_audiences sibling of audience_evidence_requirements on buy_products purchases and list_products offer_filters, and record it in the accepted purchase - snapshot. 3.3 carries it only on get_products filters and - create_media_buy packages, because the purchase and offer-filter - schemas are closed and a minor release does not change a closed schema. + snapshot. 3.3 carries it only on create_media_buy packages. It was + withdrawn from the deprecated get_products filters after + 3.3.0-beta.5 (adcp#8501). The purchase input and offer filters are open + in 3.3 but do not define it, and the accepted purchase snapshot, + product-purchase.json, is held closed with the commercial terms until + 4.0. observed_by: none: reason: >- @@ -323,6 +326,28 @@ checks: The canonical schema is closed in 3.x and does not carry the field, so a 3.x seller run cannot send or observe it. + - id: canonical_price_adjustments_required_in_4_0 + issue: 7659 + change: new_requirement + applies_to: [sellers] + detection: "A seller that prices format option or placement selections and dated windows from a published rate table cannot carry that table as price_adjustments on a canonical pricing option." + fix: >- + Nothing in 3.3. The experimental price_adjustments table + (media_buy.price_adjustments) shipped in 3.3.0-beta.1 through + 3.3.0-beta.5 on the pricing options of the deprecated get_products and + is withdrawn after beta.5 (adcp#8501): 3.3 adds no field that exists only on a deprecated task, + and canonical-pricing-option.json is held closed with the commercial + terms until 4.0. Do not return a + table or emit error-details/price-adjustments-mismatch.json. Until 4.0, + return a priced option per configured product. 4.0 adds the table to + the canonical pricing option. + observed_by: + none: + reason: >- + A seller-authored field on the canonical pricing option, which is + held closed until 4.0, and 3.3 has no wire form for it after beta.5. + A 3.x run cannot observe it. + # Schema nodes marked for 4.0 removal that no check covers yet. `change` names # the removal, `issue` is its 4.0 tracking issue (required), and `reason` says # why a 3.x agent is not graded on it. @@ -339,7 +364,6 @@ schema_removals_not_checked: - "creative/list-creative-formats-request.json#/properties/format_ids" - "media-buy/list-creative-formats-request.json#/properties/format_ids" - "media-buy/package-request.json#/properties/format_ids" - - "media-buy/package-forecast-input.json#/properties/format_ids" - change: "Exact plural format_ids projections outside the product" issue: 7629 diff --git a/static/schemas/source/core/execution-requirement-readiness.json b/static/schemas/source/core/execution-requirement-readiness.json index e667e4c3689..ed3817838db 100644 --- a/static/schemas/source/core/execution-requirement-readiness.json +++ b/static/schemas/source/core/execution-requirement-readiness.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/core/execution-requirement-readiness.json", "title": "Execution Requirement Readiness", - "description": "Experimental (`media_buy.execution_readiness`). Whether the caller's account can satisfy one entry of a product's `execution_requirements[]`. Account-scoped; appears only in the `get_products` `execution_readiness` map and MUST NOT be disclosed across accounts. Advisory: `create_media_buy` revalidates.", + "description": "Experimental (`media_buy.execution_readiness`). Whether the caller's account can satisfy one entry of a product's `execution_requirements[]`. Account-scoped; appears only in the `list_products` `execution_readiness` map and MUST NOT be disclosed across accounts. Advisory: the purchase task revalidates.", "type": "object", "properties": { "requirement": { @@ -16,7 +16,7 @@ "binding_field": { "type": "string", "minLength": 1, - "description": "Where the buyer binds the resource, in the form of `error.field`. Omitted for `downstream_connection`. For `event_source` and `catalog`, SHOULD be present when `ready` or `selection_required`." + "description": "Where the buyer binds the resource, in the form of `error.field`, on `buy_products`, the next step from `list_products`: `purchases[].optimization_goals[].event_sources[].event_source_id` for an event source, `purchases[].catalog_ids[]` for a catalog. Not the legacy `create_media_buy` `packages[]` paths. Omitted for `downstream_connection`. For `event_source` and `catalog`, SHOULD be present when `ready` or `selection_required`." }, "resolved": { "type": "object", @@ -282,7 +282,7 @@ "event_types": ["purchase"] }, "readiness_status": "selection_required", - "binding_field": "packages[].optimization_goals[].event_sources[].event_source_id", + "binding_field": "purchases[].optimization_goals[].event_sources[].event_source_id", "candidates": [ { "resource_id": "es_main_site", diff --git a/static/schemas/source/core/product-execution-readiness.json b/static/schemas/source/core/product-execution-readiness.json index 3fee5d15b45..b2e5d2dc0c1 100644 --- a/static/schemas/source/core/product-execution-readiness.json +++ b/static/schemas/source/core/product-execution-readiness.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/core/product-execution-readiness.json", "title": "Product Execution Readiness", - "description": "Experimental (`media_buy.execution_readiness`). Whether the caller's account can satisfy a product's `execution_requirements[]`: one entry per requirement plus a rollup. Carried only in the `get_products` `execution_readiness` map. Annotate, never filter: a product that is not `ready`, including `unknown`, may still be runnable.", + "description": "Experimental (`media_buy.execution_readiness`). Whether the caller's account can satisfy a product's `execution_requirements[]`: one entry per requirement plus a rollup. Carried only in the `list_products` `execution_readiness` map. Annotate, never filter: a product that is not `ready`, including `unknown`, may still be runnable.", "type": "object", "properties": { "readiness_status": { diff --git a/static/schemas/source/core/product-execution-requirement.json b/static/schemas/source/core/product-execution-requirement.json index 51ace3a0fff..5e376cc0e8a 100644 --- a/static/schemas/source/core/product-execution-requirement.json +++ b/static/schemas/source/core/product-execution-requirement.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/core/product-execution-requirement.json", "title": "Product Execution Requirement", - "description": "Experimental. One account resource a package on the product needs before it can be created. `kind` determines the binding: `event_source` via `packages[].optimization_goals[].event_sources[]`, `catalog` via `packages[].catalogs[]`, `downstream_connection` by completing the connection. Account-independent: MUST NOT carry account-specific resource IDs or names. Alternatives inside one requirement are any-of.", + "description": "Experimental. One account resource a purchase (or legacy package) on the product needs before it can be bought. `kind` determines the binding: `event_source` via `purchases[].optimization_goals[].event_sources[]` on `buy_products` (`packages[].optimization_goals[].event_sources[]` on the legacy `create_media_buy`), `catalog` via `purchases[].catalog_ids[]` naming a synced catalog (`packages[].catalogs[]` on the legacy task), `downstream_connection` by completing the connection. Account-independent: MUST NOT carry account-specific resource IDs or names. Alternatives inside one requirement are any-of.", "discriminator": { "propertyName": "kind" }, @@ -35,7 +35,7 @@ { "type": "object", "title": "Catalog Execution Requirement", - "description": "Each package needs a catalog. Satisfied by a `packages[].catalogs[]` entry whose `type` is in `catalog_types`. App promotion uses `[\"app\"]`; app items carry `app_id`, `bundle_id`, `apple_id`, and `store_url`. Every listed type MUST also appear in the product's `catalog_types`.", + "description": "Each purchase or package needs a catalog. Satisfied on `buy_products` by a `purchases[].catalog_ids[]` entry naming a synced catalog whose `type` is in `catalog_types`, and on the legacy `create_media_buy` by a `packages[].catalogs[]` entry of such a type. App promotion uses `[\"app\"]`; app items carry `app_id`, `bundle_id`, `apple_id`, and `store_url`. Every listed type MUST also appear in the product's `catalog_types`.", "properties": { "kind": { "type": "string", diff --git a/static/schemas/source/core/product-filters.json b/static/schemas/source/core/product-filters.json index c5ea2168be1..182c502c07b 100644 --- a/static/schemas/source/core/product-filters.json +++ b/static/schemas/source/core/product-filters.json @@ -676,23 +676,10 @@ "$ref": "/schemas/core/audience-evidence-requirements.json", "description": "Buyer policy for evaluating Product.audience_evidence. In required mode, sellers MUST apply the evidence_presence and admissibility semantics and exclude non-matching products; they MUST NOT ignore an unsupported hard requirement. In preferred mode, sellers use matches for ranking and explain the evidence selected. Buyers SHOULD inspect media_buy.audience_evidence capabilities before sending this object." }, - "target_audiences": { - "type": "array", - "x-status": "experimental", - "x-added-in": "3.3.0", - "items": { "$ref": "/schemas/core/audience-evidence-target.json" }, - "minItems": 1, - "maxItems": 10, - "uniqueItems": true, - "description": "Experimental (media_buy.audience_evidence_targets). Audiences the buyer wants evidence for, evaluated against the admissibility rules, requirement_mode and evidence_presence of the sibling audience_evidence_requirements, which MUST be present with it. Targets combine with AND. required excludes a product whose published evidence misses any target; preferred only ranks and explains via audience_evidence_selections. A seller that does not list media_buy.audience_evidence_targets in experimental_features MUST NOT apply it and, when audience_evidence_requirements.requirement_mode is required, MUST fail with UNSUPPORTED_FEATURE. Not a targeting predicate." - }, "ext": { "$ref": "/schemas/core/ext.json", "description": "Vendor-namespaced extension parameters for seller-specific filter criteria not covered by standard fields. Keys MUST be namespaced under a vendor or platform key (e.g., ext.gam, ext.platform_x). Sellers MUST treat all values as untrusted buyer input; do not interpolate into LLM prompts, SQL queries, or system commands without sanitization. Persistent use of an extension key across multiple buyers is a signal to propose standardization." } }, - "dependencies": { - "target_audiences": ["audience_evidence_requirements"] - }, "additionalProperties": true } diff --git a/static/schemas/source/core/product.json b/static/schemas/source/core/product.json index 58d2b9e0b9d..7f26544f889 100644 --- a/static/schemas/source/core/product.json +++ b/static/schemas/source/core/product.json @@ -116,7 +116,7 @@ }, "pricing_options": { "type": "array", - "description": "Available pricing models for this product. Fixed prices and auction floors are binding for every later targeting selection permitted by this product's overlay_support; price_guidance remains non-binding. Declaring broad overlay support alongside a binding option is therefore a uniform-price promise, not permission to calculate a different price at create time, except for adjustments the selected fixed-price option itself declares in price_adjustments: those rows are part of the option's binding terms, and the resolved rate follows from the buyer's selections by the deterministic rules in price-adjustments.json. A price_adjustments table is optional and has equal standing with a fully priced offer: a seller that does not publish one (for example a yield-managed seller) returns priced options, whose price applies only to what was quoted, and is not expected to publish its method. A seller with other value-dependent rates MUST return a request-specific configured product after rediscovery with concrete targeting, split the inventory into separately priced products, or expose only non-binding guidance until it can issue a binding option. The seller MUST mint a new pricing_option_id whenever a binding price, floor, currency, model, or priced applicability changes. It MUST NOT silently reprice a create request or reuse the selected option ID with different terms.", + "description": "Available pricing models for this product. Fixed prices and auction floors are binding for every later targeting selection permitted by this product's overlay_support; price_guidance remains non-binding. Declaring broad overlay support alongside a binding option is therefore a uniform-price promise, not permission to calculate a different price at create time. A seller with value-dependent rates MUST return a request-specific configured product after rediscovery with concrete targeting, split the inventory into separately priced products, or expose only non-binding guidance until it can issue a binding option. The seller MUST mint a new pricing_option_id whenever a binding price, floor, currency, model, or priced applicability changes. It MUST NOT silently reprice a create request or reuse the selected option ID with different terms.", "items": { "$ref": "/schemas/core/pricing-option.json" }, @@ -244,7 +244,7 @@ }, "overlay_support": { "$ref": "/schemas/core/targeting-overlay-support.json", - "description": "Binding product-scoped targeting dimensions the buyer may set independently on packages after discovery. Presence guarantees selectable capability subject to disclosed limits, not inventory or a forecast for every possible value. Targeting satisfied only through inherent product scope does not appear here. Returned products MUST cover every field requested through get_products.required_overlay_support. Selecting a value priced by the chosen option's price_adjustments (currently placement_selection and format option selection) changes the resolved rate only as that table declares. A later supported selection with no available inventory returns PRODUCT_UNAVAILABLE on create; an update outside the original priced envelope may return REQUOTE_REQUIRED." + "description": "Binding product-scoped targeting dimensions the buyer may set independently on packages after discovery. Presence guarantees selectable capability subject to disclosed limits, not inventory or a forecast for every possible value. Targeting satisfied only through inherent product scope does not appear here. Returned products MUST cover every field requested through get_products.required_overlay_support. A later supported selection with no available inventory returns PRODUCT_UNAVAILABLE on create; an update outside the original priced envelope may return REQUOTE_REQUIRED." }, "media_buy_support": { "$ref": "/schemas/core/media-buy-support.json", @@ -524,7 +524,7 @@ }, "collections": { "type": "array", - "description": "Collections available in this product. A non-empty array is the complete roster. `[]` means the seller does not disclose it (undisclosed); absent makes no collection declaration. It bounds nothing. MUST NOT be `[]` on a response served below 3.3. Each entry references collections declared in an adagents.json by domain and collection ID. Full collection objects arrive in the response's top-level collections array when the request sets include_collections and the seller supports it (experimental, media_buy.collection_cards); otherwise buyers resolve them from the referenced adagents.json, which remains the authorization source either way. Product selectors must name explicit collection_ids — the domain-only bulk-grant selector form is for authorization scoping, not product composition.", + "description": "Collections available in this product. A non-empty array is the complete roster. `[]` means the seller does not disclose it (undisclosed); absent makes no collection declaration. It bounds nothing. MUST NOT be `[]` on a response served below 3.3. Each entry references collections declared in an adagents.json by domain and collection ID. Buyers resolve full collection objects from the referenced adagents.json. Product selectors must name explicit collection_ids — the domain-only bulk-grant selector form is for authorization scoping, not product composition.", "items": { "allOf": [ { "$ref": "/schemas/core/collection-selector.json" }, @@ -862,32 +862,6 @@ "required": ["property_targeting_allowed"] } }, - { - "if": { - "properties": { - "pricing_options": { - "contains": { - "properties": { - "price_adjustments": { - "contains": { - "properties": { "dimension": { "const": "placement_selection" } }, - "required": ["dimension"] - } - } - }, - "required": ["price_adjustments"] - } - } - }, - "required": ["pricing_options"] - }, - "then": { - "properties": { - "overlay_support": { "required": ["placement_selection"] } - }, - "required": ["overlay_support"] - } - }, { "description": "Selectable placement products cannot also contain unavoidable included placements because placement_selection is the complete purchased set.", "if": { diff --git a/static/schemas/source/core/targeting-overlay-support.json b/static/schemas/source/core/targeting-overlay-support.json index 9f3d705b770..ad3fd6a893b 100644 --- a/static/schemas/source/core/targeting-overlay-support.json +++ b/static/schemas/source/core/targeting-overlay-support.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/core/targeting-overlay-support.json", "title": "Targeting Overlay Support", - "description": "Product-scoped package targeting dimensions that may be supplied or changed after discovery. This is the seller response shape and may disclose seller limits such as max_values_per_package, max_packages, and max_references. Product.overlay_support is the binding selectable-targeting contract: presence means the seller can apply protocol-valid values within the declared systems, countries, values, types, versions, and limits. Inherent product coverage alone does not satisfy a future-support requirement. Support does not guarantee inventory or a value-specific forecast before values are supplied; fixed prices and floors remain binding for supported selections, uniform across values except for adjustments declared by the selected fixed-price pricing option's price_adjustments, which price format option and placement_selection selections and dated windows. geo_regions and geo_regions_exclude are independent: structured support either exhaustively declares every value active in the seller's support snapshot for a country or lists the exact finite selectable subset. Buyer minimums use targeting-overlay-requirements.json. A requirement value of true matches true or any valid support object; an object requirement matches true or a containing support object. The daypart_targets boolean is the backward-compatible exception: true promises inventory_local and whole-hour granularity only, and structured support opts into IANA zones and finer time_granularity. Every valid structured support object represents a positive capability; empty, extension-only, and false-only objects are invalid. Unrequested object fields and numeric seller limits do not participate in matching. A product declares at most one of frequency_cap: true and frequency_cap_support. Legacy frequency_cap: true keeps its broad meaning within seller-wide limits, including update support. A constrained or create-only product instead advertises frequency_cap_support, so older buyers safely treat it as unsupported.", + "description": "Product-scoped package targeting dimensions that may be supplied or changed after discovery. This is the seller response shape and may disclose seller limits such as max_values_per_package, max_packages, and max_references. Product.overlay_support is the binding selectable-targeting contract: presence means the seller can apply protocol-valid values within the declared systems, countries, values, types, versions, and limits. Inherent product coverage alone does not satisfy a future-support requirement. Support does not guarantee inventory or a value-specific forecast before values are supplied; fixed prices and floors remain binding for supported selections. geo_regions and geo_regions_exclude are independent: structured support either exhaustively declares every value active in the seller's support snapshot for a country or lists the exact finite selectable subset. Buyer minimums use targeting-overlay-requirements.json. A requirement value of true matches true or any valid support object; an object requirement matches true or a containing support object. The daypart_targets boolean is the backward-compatible exception: true promises inventory_local and whole-hour granularity only, and structured support opts into IANA zones and finer time_granularity. Every valid structured support object represents a positive capability; empty, extension-only, and false-only objects are invalid. Unrequested object fields and numeric seller limits do not participate in matching. A product declares at most one of frequency_cap: true and frequency_cap_support. Legacy frequency_cap: true keeps its broad meaning within seller-wide limits, including update support. A constrained or create-only product instead advertises frequency_cap_support, so older buyers safely treat it as unsupported.", "type": "object", "definitions": { "supported": { diff --git a/static/schemas/source/creative/sync-creatives-request.json b/static/schemas/source/creative/sync-creatives-request.json index 5db6fa5709d..b5d3175ed7b 100644 --- a/static/schemas/source/creative/sync-creatives-request.json +++ b/static/schemas/source/creative/sync-creatives-request.json @@ -193,6 +193,7 @@ "deprecated": true, "description": "Deprecated additive assignment shorthand. Each entry upserts one creative-to-package assignment. Use assignment_operations for explicit assign, unassign, and replace semantics. Standalone creative agents that do not manage media buys ignore this field. A pending_review or rejected library creative MAY be assigned if the reference and other assignment constraints are valid; sellers MUST NOT reject or remove an assignment solely for its review status. Only package-approved eligible creatives may serve. See the package start_requires_all_creatives_approved policy and docs/media-buy/specification.mdx#starting-with-assigned-creatives-under-review.", "items": { + "description": "This deprecated row rejects `trackers` and `landing_page_url`, which belong only to an `assignment_operations` `assign`.", "type": "object", "properties": { "creative_id": { @@ -205,18 +206,6 @@ "description": "ID of the package to assign the creative to", "x-entity": "package" }, - "trackers": { - "type": "array", - "items": { "$ref": "/schemas/core/assignment-tracker.json" }, - "minItems": 1, - "description": "Additional measurement trackers for this creative on this package only, fired alongside the creative's own trackers without changing the library creative, its revision, or its approval. Requires creative.supports_assignment_trackers: true; buyers MUST NOT send this field otherwise and unsupported agents MUST reject it with UNSUPPORTED_FEATURE. The seller MUST fire every accepted tracker at its declared event or reject the assignment through existing assignment errors; trackers MUST NOT be silently dropped. Creative and assignment trackers together count against the effective format's tracker-slot limits, including canonical params.slots[].max and legacy repeatable-group max_count. Each assignment tracker consumes one compatible tracker-slot occurrence without moving creative assets (impression_tracker takes impression, click_tracker takes click, viewability_tracker takes viewable_* and audible_video_complete, any other pixel_tracker slot takes any event); reject if no allocation satisfies each slot's event and count constraints. These limits apply only when the effective format declares at least one tracker slot: a format that declares none makes no slot-limit claim, and the seller still fires every accepted tracker or rejects the assignment. Each accepted occurrence fires once per logical event; identical URLs are not deduplicated. A supplied list replaces the prior assignment tracker list. Omission on an additive upsert preserves existing assignment trackers. To clear them, atomically unassign then assign without this field, retaining any other authored assignment settings. Empty arrays and null are not accepted.", - "x-added-in": "3.3.0" - }, - "landing_page_url": { - "$ref": "/schemas/core/macro-bearing-url.json", - "description": "Override the creative's click-through destination for this creative on this package only, without changing the library creative. The override applies to every click-through destination for this assignment, including per-state destinations; partial application MUST be rejected. AdCP macros follow the same rules as the creative's own click-through without declarations, retaining existing 3.x compatibility behavior. Declarations on the original creative assets do not transfer to this URL. Requires creative.supports_assignment_landing_page: true; buyers MUST NOT send this field otherwise and sellers without the capability MUST reject it with UNSUPPORTED_FEATURE. The seller MUST serve the override or reject the assignment through existing assignment errors, including when an embedded HTML, JavaScript, or VAST click cannot be overridden. Creative approval remains valid; destination review applies to the assignment. Omission on an additive upsert preserves an existing override. To restore inheritance, atomically unassign then assign without this field; null is not accepted.", - "x-added-in": "3.3.0" - }, "weight": { "type": "number", "description": "Relative delivery weight (0-100). When multiple creatives are assigned to the same package, weights determine impression distribution proportionally. When omitted, the creative receives equal rotation with other unweighted creatives. A weight of 0 means the creative is assigned but paused (receives no delivery).", @@ -236,6 +225,7 @@ "creative_id", "package_id" ], + "not": { "anyOf": [{ "required": ["trackers"] }, { "required": ["landing_page_url"] }] }, "additionalProperties": true, "x-adcp-validation": { "verifier_constraints": { diff --git a/static/schemas/source/error-details/price-adjustments-mismatch.json b/static/schemas/source/error-details/price-adjustments-mismatch.json deleted file mode 100644 index f08a246fae1..00000000000 --- a/static/schemas/source/error-details/price-adjustments-mismatch.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "/schemas/error-details/price-adjustments-mismatch.json", - "title": "Price Adjustments Mismatch Details", - "x-added-in": "3.3.0", - "x-status": "experimental", - "description": "Recommended details shape for an INVALID_REQUEST that rejects a buyer-supplied pricing whose fixed_price or price_breakdown differs from the price the selected option's price_adjustments table resolves to for the purchase's selections and flight. Carries the resolved values so the buyer can see which row it disagrees on. Experimental (media_buy.price_adjustments).", - "type": "object", - "properties": { - "resolved_fixed_price": { - "type": "number", - "minimum": 0, - "description": "The price the table resolves to for this purchase." - }, - "resolved_price_breakdown": { - "$ref": "/schemas/pricing-options/price-breakdown.json", - "description": "The resolved breakdown: declared adjustments followed by one entry per fired row." - } - }, - "required": [ - "resolved_fixed_price" - ], - "additionalProperties": true -} diff --git a/static/schemas/source/media-buy/get-products-rejected.json b/static/schemas/source/media-buy/get-products-rejected.json index 651e223e959..7a33cd59d95 100644 --- a/static/schemas/source/media-buy/get-products-rejected.json +++ b/static/schemas/source/media-buy/get-products-rejected.json @@ -51,11 +51,6 @@ "products" ] }, - { - "required": [ - "collections" - ] - }, { "required": [ "proposals" diff --git a/static/schemas/source/media-buy/get-products-request.json b/static/schemas/source/media-buy/get-products-request.json index 7de1d0b25ee..55fece9517b 100644 --- a/static/schemas/source/media-buy/get-products-request.json +++ b/static/schemas/source/media-buy/get-products-request.json @@ -8,29 +8,6 @@ { "$ref": "/schemas/core/version-envelope.json" }, - { - "description": "Structured package forecasts are read-only refinement and cannot be mixed with proposal finalization.", - "if": { - "properties": { - "refine": { "contains": { "required": ["package"] } } - }, - "required": ["refine"] - }, - "then": { - "properties": { - "buying_mode": { "const": "refine" }, - "refine": { - "items": { - "not": { - "properties": { "action": { "const": "finalize" } }, - "required": ["action"] - } - } - } - }, - "required": ["buying_mode"] - } - }, { "description": "Conditional wholesale feed version requests are only valid for wholesale product feed reads.", "if": { @@ -80,7 +57,7 @@ "description": "Array of change requests for iterating on products and proposals from a previous get_products response. Each entry declares a scope (request, product, or proposal) and what the buyer is asking for. Only valid when buying_mode is 'refine'. The seller responds to each entry via refinement_applied in the response, matched by position.\n\nFinalize-exclusivity rule: if any entry has `action: 'finalize'`, ALL entries in the array MUST be proposal-scoped with `action: 'finalize'` — mixing finalize entries with `include`/`omit` entries or with request- / product-scoped entries MUST be rejected by the seller with `INVALID_REQUEST`. Finalize is a commit, not a refinement; the buyer expressing intent to commit means refinements have already converged. Buyers needing to refine AND commit in close succession sequence the calls: first a refine call (no finalize), then a finalize call against the resulting `proposal_id`(s).\n\nMulti-finalize semantics: multiple finalize entries against different `proposal_id` values in a single call are allowed and MUST be **atomic at the observation point** — sellers MUST NOT return a success response unless every named proposal has both completed and been persisted as committed. Pre-commit validation runs before any side-effects (inventory pull, terms lock, governance attestation); if any proposal fails validation, the seller MUST reject the entire call without committing any of the named proposals. There is no rollback operation in the spec — an `unfinalize` would itself be a new mutation surface; the atomicity guarantee runs entirely on the seller's pre-commit validation gate, not on post-commit reversal. Sellers that cannot guarantee atomic pre-commit validation MUST reject multi-finalize arrays with `MULTI_FINALIZE_UNSUPPORTED` (preferred — distinguishes seller-side capability gap from a malformed request) or `INVALID_REQUEST` (acceptable fallback for sellers on a pre-3.1 error catalog). If a mid-commit failure occurs *after* validation passed but before all proposals persist (e.g., a downstream ad server fails between commits one and two), the seller MUST return `INTERNAL_ERROR` with `refinement_applied[]` carrying per-position outcomes — the spec does NOT define a recovery path for this case, and buyers SHOULD treat the resulting state as undefined and re-read via `get_media_buys` / equivalent before retrying. Buyers MUST NOT assume multi-finalize support without a successful first attempt — there is no capability flag for this; the failure response is the discovery surface. Buyers whose intent specifically requires atomic commit (e.g., budget-shared proposals where one finalizing without the other is incoherent) MUST be prepared to abandon the intent if the seller returns `MULTI_FINALIZE_UNSUPPORTED` — there is no recovery for that loss of buyer intent beyond sequencing single-finalize calls and accepting the looser commit guarantee.", "minItems": 1, "items": { - "description": "Only the product scope takes `package`; the request and proposal scopes reject it.", + "description": "No scope takes `package`: exact-package forecasts are withdrawn from this deprecated task (adcp#8501), so every scope rejects it.", "type": "object", "discriminator": { "propertyName": "scope" @@ -125,20 +102,10 @@ "type": "string", "minLength": 1, "description": "What the buyer is asking for on this product. For 'include': specific changes to request (e.g., 'add 16:9 format'). For 'more_like_this': what 'similar' means (e.g., 'same audience but video format'). Ignored when action is 'omit'." - }, - "package": { - "$ref": "/schemas/media-buy/package-forecast-input.json", - "x-added-in": "3.3.0", - "description": "Optional exact package to forecast without booking, holding, or reserving inventory. Valid only with action include (including the omitted default). The seller MUST return refinement_applied for the whole request. For this entry, applied confirms an availability forecast for exactly these inputs; unable with non-empty notes reports unsupported or unresolvable inputs, without a substitute forecast. Entries are forecast independently, without subtracting other proposed packages in this call. See the refinement guide for flight, targeting, and goal resolution." } }, "required": ["scope", "product_id"], - "allOf": [ - { - "if": { "required": ["package"] }, - "then": { "properties": { "action": { "const": "include" } } } - } - ], + "not": { "required": ["package"] }, "additionalProperties": true }, { @@ -223,15 +190,9 @@ "description": "DEPRECATED discovery-only property filter. On compact discovery tasks use criteria.offer_filters.property_list to preserve product eligibility. Use targeting_overlay.property_list only when the buyer intends a delivery constraint, or required_overlay_support.property_list for future selectability. A facade MUST NOT convert this discovery filter into delivery targeting.", "deprecated": true }, - "include_execution_readiness": { - "type": "boolean", - "x-status": "experimental", - "x-added-in": "3.3.0", - "description": "Experimental (`media_buy.execution_readiness`). When true and `account` is present, a seller that lists `media_buy.execution_readiness` in `experimental_features` returns the response-level `execution_readiness` map for the products on the response. Opt-in because computing it can require reads on the seller's platform. Ignored when `account` is absent; an `account` that does not resolve still returns `ACCOUNT_NOT_FOUND`. Sellers that do not support it ignore the field. Default false." - }, "fields": { "type": "array", - "description": "Specific product fields to include in the response. When omitted, all fields are returned. Use for lightweight discovery calls where only a subset of product data is needed. product_id and name are always included. `format_ids` is a deprecated 3.x compatibility projection; new integrations request canonical `format_options`. Safety-critical request-specific fields override projection: Product.targeting_resolution and expires_at MUST be included whenever the seller returns modifications, overlay_support MUST be included when required_overlay_support was requested, media_buy_support MUST be included when required_media_buy_support or media_buy_frequency_cap was requested, list_applications MUST be included when a property or collection list is in the effective targeting, and audience_evidence_selections MUST be included when filters.audience_evidence_requirements affects eligibility or ranking. A structured refine package entry with an applied outcome MUST include forecast even when projection omitted it. fields controls the optional audience_evidence payload, not either decision receipt. Response-level brief targeting confirmation is not a projected product field. A projection that omits collections also omits the response-level collections array.", + "description": "Specific product fields to include in the response. When omitted, all fields are returned. Use for lightweight discovery calls where only a subset of product data is needed. product_id and name are always included. `format_ids` is a deprecated 3.x compatibility projection; new integrations request canonical `format_options`. Safety-critical request-specific fields override projection: Product.targeting_resolution and expires_at MUST be included whenever the seller returns modifications, overlay_support MUST be included when required_overlay_support was requested, media_buy_support MUST be included when required_media_buy_support or media_buy_frequency_cap was requested, list_applications MUST be included when a property or collection list is in the effective targeting, and audience_evidence_selections MUST be included when filters.audience_evidence_requirements affects eligibility or ranking. fields controls the optional audience_evidence payload, not either decision receipt. Response-level brief targeting confirmation is not a projected product field.", "minItems": 1, "items": { "anyOf": [ @@ -261,13 +222,6 @@ ] } }, - "include_collections": { - "type": "boolean", - "default": false, - "description": "Experimental (media_buy.collection_cards). When true, asks the seller to return the response-level collections array: the full object for each collection the returned products' collections selectors reference. Sellers MUST NOT return collections unless this is true, and when it is true they SHOULD include every referenced collection. Part of the wholesale_feed_version scope: without it collection copies are outside the version, and with it the version also changes when any returned collection copy changes. This request accepts unknown fields, so a seller that does not implement the feature ignores the flag; buyers detect omitted collections by comparing product selectors with the returned array and resolve those from the publisher's adagents.json.", - "x-status": "experimental", - "x-added-in": "3.3.0" - }, "time_budget": { "allOf": [ { @@ -286,7 +240,7 @@ }, "if_wholesale_feed_version": { "type": "string", - "description": "Opaque wholesale_feed_version token returned by a prior wholesale-mode get_products response from this agent. Only valid when buying_mode is wholesale. When provided, the seller compares against its current wholesale product feed version for the buyer's cache_scope and MAY return an unchanged: true response (with products omitted) if nothing has changed. The token is scope-keyed: buyers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, include_collections) for cache_scope: 'public'; that tuple plus account identity for cache_scope: 'account'. An absent include_collections and false are the same scope; a token issued under the other include_collections setting is a mismatch and gets the full payload. pagination.cursor is NOT part of the scoping tuple. Backward-compatible: pre-v3.1 agents that ignore this field simply return the full payload, same as the unchanged-server path. See specs/wholesale-feed-webhooks.md for the full sync pattern." + "description": "Opaque wholesale_feed_version token returned by a prior wholesale-mode get_products response from this agent. Only valid when buying_mode is wholesale. When provided, the seller compares against its current wholesale product feed version for the buyer's cache_scope and MAY return an unchanged: true response (with products omitted) if nothing has changed. The token is scope-keyed: buyers cache `(cache_scope, wholesale_feed_version)` pairs. Scoping dimensions: (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog) for cache_scope: 'public'; that tuple plus account identity for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. Backward-compatible: pre-v3.1 agents that ignore this field simply return the full payload, same as the unchanged-server path. See specs/wholesale-feed-webhooks.md for the full sync pattern." }, "if_pricing_version": { "type": "string", diff --git a/static/schemas/source/media-buy/get-products-response.json b/static/schemas/source/media-buy/get-products-response.json index e08b40461c3..26ba8c20915 100644 --- a/static/schemas/source/media-buy/get-products-response.json +++ b/static/schemas/source/media-buy/get-products-response.json @@ -62,16 +62,6 @@ "$ref": "/schemas/core/product.json" } }, - "collections": { - "type": "array", - "description": "Experimental (media_buy.collection_cards). Full collection objects for collections referenced by the collections selectors of the returned products. Sellers MUST NOT return this array unless the request set include_collections to true; when it is set, sellers SHOULD include every referenced collection and MUST NOT include one that no returned product references. At most one entry per (publisher_domain, collection_id). If a key appears more than once, that collection is unresolvable from this response; buyers fall back to the publisher's adagents.json, as they do for an omitted collection, and ignore entries that no returned product references. These are convenience copies, never authorization evidence: a copy wins over adagents.json only on images, sample_content, url, description, season, cadence and distribution[].followers (see core/response-collection.json). Present only alongside products.", - "minItems": 1, - "items": { - "$ref": "/schemas/core/response-collection.json" - }, - "x-status": "experimental", - "x-added-in": "3.3.0" - }, "targeting_resolution": { "$ref": "/schemas/media-buy/get-products-targeting-resolution.json", "description": "Request-level confirmation of structured hard targeting inferred from the brief. Sellers MUST include this when their structured interpretation of hard prose materially affects product eligibility, pricing, or forecasting; otherwise inclusion is a best practice. Omitted when no hard targeting was inferred from the brief." @@ -148,7 +138,7 @@ }, "refinement_applied": { "type": "array", - "description": "Seller's response to each change request in the refine array, matched by position. Each entry acknowledges whether the corresponding ask was applied, partially applied, or unable to be fulfilled. MUST contain the same number of entries in the same order as the request's refine array. Only present when the request used buying_mode: 'refine'. Each entry MUST echo the request entry's scope and — for product and proposal scopes — the matching id field (product_id or proposal_id), so orchestrators can cross-validate alignment. In AdCP 3.3, when any refine entry carries package, this array is REQUIRED for the entire request. For each package entry, applied requires result_product_id, resolved_start_time, and resolved_end_time and confirms that the mapped returned product forecast uses exactly the resolved package inputs, including its goal; unable requires non-empty notes explaining why those exact inputs could not be forecast, and the product MUST NOT carry a substitute forecast. partial MUST NOT be used to imply exact package forecast support. Insufficient inventory is an applied forecast with availability_status unavailable, not an unable outcome.", + "description": "Seller's response to each change request in the refine array, matched by position. Each entry acknowledges whether the corresponding ask was applied, partially applied, or unable to be fulfilled. MUST contain the same number of entries in the same order as the request's refine array. Only present when the request used buying_mode: 'refine'. Each entry MUST echo the request entry's scope and — for product and proposal scopes — the matching id field (product_id or proposal_id), so orchestrators can cross-validate alignment.", "items": { "type": "object", "discriminator": { @@ -193,26 +183,6 @@ "type": "string", "description": "Echoes product_id from the corresponding refine entry." }, - "result_product_id": { - "type": "string", - "minLength": 1, - "x-entity": "product", - "x-added-in": "3.3.0", - "description": "Required for an applied structured package forecast. Identifies exactly one returned Product carrying this entry's exact forecast, even when its configured ID differs from the request product_id. The requested pricing_option_id and pricing terms MUST remain unchanged. Buyers use this ID at create." - }, - "resolved_start_time": { - "type": "string", - "format": "date-time", - "not": { "const": "asap" }, - "x-added-in": "3.3.0", - "description": "Required with result_product_id. Exact forecast flight start after resolving explicit package timestamps or date-filter defaults. Buyers materialize this timestamp on the package at create." - }, - "resolved_end_time": { - "type": "string", - "format": "date-time", - "x-added-in": "3.3.0", - "description": "Required with result_product_id. Exact forecast flight end after resolving explicit package timestamps or date-filter defaults. Buyers materialize this timestamp on the package at create. MUST be after resolved_start_time." - }, "status": { "type": "string", "enum": [ @@ -232,21 +202,6 @@ "product_id", "status" ], - "allOf": [ - { - "if": { - "anyOf": [ - { "required": ["result_product_id"] }, - { "required": ["resolved_start_time"] }, - { "required": ["resolved_end_time"] } - ] - }, - "then": { - "properties": { "status": { "const": "applied" } }, - "required": ["result_product_id", "resolved_start_time", "resolved_end_time"] - } - } - ], "additionalProperties": true }, { @@ -411,7 +366,7 @@ }, "wholesale_feed_version": { "type": "string", - "description": "Opaque token representing the version of the wholesale product feed state used to compose this response. Sellers that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so buyers can cache and probe later. Buyers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A buyer caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, include_collections) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. Without include_collections, collection copies are outside the version; with include_collections true, the version also changes when any returned collection copy changes, and sellers issue distinct tokens for the two settings. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model.", + "description": "Opaque token representing the version of the wholesale product feed state used to compose this response. Sellers that implement conditional-fetch (if_wholesale_feed_version) MUST return this on every wholesale-mode response so buyers can cache and probe later. Buyers MUST treat the value as opaque — no format, no ordering, no inspection. The token is scope-keyed: it describes a version for the cache_scope declared on this response, NOT a global agent version. A buyer caches `(cache_scope, wholesale_feed_version)` pairs and presents the matching token on the next request. Scoping dimensions: (agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog) for cache_scope: 'public'; that tuple plus account_id for cache_scope: 'account'. pagination.cursor is NOT part of the scoping tuple. See specs/wholesale-feed-webhooks.md for the full cache layering model.", "x-adcp-validation": { "verifier_constraints": { "required_for_wholesale_request": { @@ -427,42 +382,6 @@ "type": "string", "description": "Opaque token representing the version of the pricing layer, including product pricing_options and nested signal_targeting_options pricing_options. When the seller supports independent pricing versioning, pricing_version changes when prices move but wholesale_feed_version changes only when structure/metadata moves. Same cache_scope keying as wholesale_feed_version. Sellers not separating these MAY omit pricing_version and use wholesale_feed_version for both." }, - "execution_readiness": { - "type": "object", - "x-status": "experimental", - "x-added-in": "3.3.0", - "description": "Experimental (`media_buy.execution_readiness`). Whether the request's `account` can satisfy the `execution_requirements[]` of the products on this response, keyed by `product_id`. Present only when the request set `include_execution_readiness: true` and carried an authorized `account`. Advisory: `create_media_buy` revalidates. Not part of the cache layer: it does not change `cache_scope`, `wholesale_feed_version`, or `pricing_version`, buyers key it by (account, `version`) and MUST NOT cache it under the public key, sellers MUST NOT put it in wholesale feed webhooks and MUST omit it on `unchanged: true` responses. Covers only this response's products; merge pages by `product_id`. See the media-buy specification, 'Per-account execution readiness'.", - "properties": { - "version": { - "type": "string", - "minLength": 1, - "description": "Opaque token for the account's readiness state, independent of `wholesale_feed_version` and `pricing_version`. Compare for equality only. Equal versions MUST imply identical entries for any product present in both responses." - }, - "evaluated_at": { - "type": "string", - "format": "date-time", - "description": "When the seller read the account's resources. Readiness may be stale by then; `create_media_buy` is authoritative." - }, - "products": { - "type": "object", - "description": "Readiness keyed by `product_id`, for returned products that declare `execution_requirements`. A missing entry means not evaluated, not ready.", - "propertyNames": { - "minLength": 1 - }, - "additionalProperties": { - "$ref": "/schemas/core/product-execution-readiness.json" - } - }, - "ext": { - "$ref": "/schemas/core/ext.json" - } - }, - "required": [ - "version", - "products" - ], - "additionalProperties": true - }, "cache_scope": { "type": "string", "enum": [ @@ -487,9 +406,6 @@ "$ref": "/schemas/core/ext.json" } }, - "dependencies": { - "collections": ["products"] - }, "if": { "properties": { "unchanged": { diff --git a/static/schemas/source/media-buy/list-products-request.json b/static/schemas/source/media-buy/list-products-request.json index c408376ae4c..8a54108e355 100644 --- a/static/schemas/source/media-buy/list-products-request.json +++ b/static/schemas/source/media-buy/list-products-request.json @@ -47,6 +47,12 @@ "x-status": "experimental", "x-added-in": "3.3.0" }, + "include_execution_readiness": { + "type": "boolean", + "description": "Experimental (`media_buy.execution_readiness`). With `account`, asks for the response-level `execution_readiness` map for the page's products. Ignored without `account`; an unresolved `account` still returns `ACCOUNT_NOT_FOUND`. Outside the `feed_version`, `pricing_version` and `cache_scope` selection. Schemas before 3.2.8 reject unknown fields here, so send it only to a seller listing `media_buy.execution_readiness` in `experimental_features`.", + "x-status": "experimental", + "x-added-in": "3.3.0" + }, "cursor": { "type": "string", "minLength": 1 }, "max_results": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "if_feed_version": { diff --git a/static/schemas/source/media-buy/list-products-response.json b/static/schemas/source/media-buy/list-products-response.json index de9430b2cc9..eb1cf8d4d8c 100644 --- a/static/schemas/source/media-buy/list-products-response.json +++ b/static/schemas/source/media-buy/list-products-response.json @@ -28,6 +28,42 @@ "x-status": "experimental", "x-added-in": "3.3.0" }, + "execution_readiness": { + "type": "object", + "x-status": "experimental", + "x-added-in": "3.3.0", + "description": "Experimental (`media_buy.execution_readiness`). Whether the request's `account` can satisfy the `execution_requirements[]` of the products on this page, keyed by `product_id`. Present only when the request set `include_execution_readiness: true` and carried an authorized `account`. Advisory: the purchase task revalidates. Not part of the cache layer: it does not change `cache_scope`, `feed_version`, or `pricing_version`, buyers key it by (account, `version`) and MUST NOT cache it under the public key, sellers MUST NOT put it in wholesale feed webhooks, and it is present only alongside products, so never on an unchanged outcome. Covers only this page's products; merge pages by `product_id`. See the media-buy specification, 'Per-account execution readiness'.", + "properties": { + "version": { + "type": "string", + "minLength": 1, + "description": "Opaque token for the account's readiness state, independent of `feed_version` and `pricing_version`. Compare for equality only. Equal versions MUST imply identical entries for any product present in both responses." + }, + "evaluated_at": { + "type": "string", + "format": "date-time", + "description": "When the seller read the account's resources. Readiness may be stale by then; the purchase task is authoritative." + }, + "products": { + "type": "object", + "description": "Readiness keyed by `product_id`, for returned products that declare `execution_requirements`. A missing entry means not evaluated, not ready.", + "propertyNames": { + "minLength": 1 + }, + "additionalProperties": { + "$ref": "/schemas/core/product-execution-readiness.json" + } + }, + "ext": { + "$ref": "/schemas/core/ext.json" + } + }, + "required": [ + "version", + "products" + ], + "additionalProperties": true + }, "next_cursor": { "type": "string", "minLength": 1, @@ -55,7 +91,8 @@ "ext": { "$ref": "/schemas/core/ext.json" } }, "dependencies": { - "collections": ["products"] + "collections": ["products"], + "execution_readiness": ["products"] }, "oneOf": [ { diff --git a/static/schemas/source/media-buy/package-forecast-input.json b/static/schemas/source/media-buy/package-forecast-input.json deleted file mode 100644 index 41bd920c58a..00000000000 --- a/static/schemas/source/media-buy/package-forecast-input.json +++ /dev/null @@ -1,138 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "/schemas/media-buy/package-forecast-input.json", - "title": "Package Forecast Input", - "description": "Proposed package for a read-only availability forecast in get_products refine mode (AdCP 3.3). Field shapes and package validation rules are shared with Package Request. The enclosing refine entry supplies product_id; it MUST NOT be repeated here. pricing_option_id and budget are required. The budget uses the selected pricing option's currency, and impressions, when supplied, has its create_media_buy goal semantics. Omitted flight boundaries inherit filters.start_date/end_date; if an exact flight or goal cannot be resolved, the seller reports unable with notes rather than guessing. Targeting inherits the effective discovery configuration and applies package-level per-dimension replacement or clearing exactly as on create. All supplied fields are forecast inputs only: no booking, hold, reservation, creative upload, or assignment is performed.", - "type": "object", - "x-added-in": "3.3.0", - "allOf": [ - { - "$ref": "/schemas/media-buy/package-request.json#/allOf/0" - }, - { - "$ref": "/schemas/media-buy/package-request.json#/allOf/1" - }, - { - "$ref": "/schemas/media-buy/package-request.json#/allOf/2" - }, - { - "not": { - "required": [ - "product_id" - ] - } - } - ], - "properties": { - "format_ids": { - "$ref": "/schemas/media-buy/package-request.json#/properties/format_ids", - "deprecated": true, - "x-removed-in": "4.0.0", - "description": "Deprecated in AdCP 3.2; removed in AdCP 4.0. Legacy named-format selector with the same receiver rules as Package Request." - }, - "format_option_refs": { - "$ref": "/schemas/media-buy/package-request.json#/properties/format_option_refs" - }, - "format_kind": { - "$ref": "/schemas/media-buy/package-request.json#/properties/format_kind" - }, - "params": { - "$ref": "/schemas/media-buy/package-request.json#/properties/params" - }, - "budget": { - "$ref": "/schemas/media-buy/package-request.json#/properties/budget" - }, - "min_spend_target": { - "$ref": "/schemas/media-buy/package-request.json#/properties/min_spend_target" - }, - "pacing": { - "$ref": "/schemas/media-buy/package-request.json#/properties/pacing" - }, - "pricing_option_id": { - "$ref": "/schemas/media-buy/package-request.json#/properties/pricing_option_id" - }, - "bid_price": { - "$ref": "/schemas/media-buy/package-request.json#/properties/bid_price", - "deprecated": true - }, - "bidding": { - "$ref": "/schemas/media-buy/package-request.json#/properties/bidding" - }, - "impressions": { - "$ref": "/schemas/media-buy/package-request.json#/properties/impressions" - }, - "daily_budget_cap": { - "$ref": "/schemas/media-buy/package-request.json#/properties/daily_budget_cap" - }, - "start_time": { - "$ref": "/schemas/media-buy/package-request.json#/properties/start_time" - }, - "end_time": { - "$ref": "/schemas/media-buy/package-request.json#/properties/end_time" - }, - "start_requires_all_creatives_approved": { - "$ref": "/schemas/media-buy/package-request.json#/properties/start_requires_all_creatives_approved" - }, - "paused": { - "$ref": "/schemas/media-buy/package-request.json#/properties/paused" - }, - "catalogs": { - "$ref": "/schemas/media-buy/package-request.json#/properties/catalogs" - }, - "optimization_goals": { - "$ref": "/schemas/media-buy/package-request.json#/properties/optimization_goals" - }, - "targeting_overlay": { - "$ref": "/schemas/media-buy/package-request.json#/properties/targeting_overlay" - }, - "audience_evidence_requirements": { - "$ref": "/schemas/media-buy/package-request.json#/properties/audience_evidence_requirements" - }, - "target_audiences": { - "$ref": "/schemas/media-buy/package-request.json#/properties/target_audiences" - }, - "audience_evidence_pins": { - "$ref": "/schemas/media-buy/package-request.json#/properties/audience_evidence_pins" - }, - "measurement_terms": { - "$ref": "/schemas/media-buy/package-request.json#/properties/measurement_terms" - }, - "performance_standards": { - "$ref": "/schemas/media-buy/package-request.json#/properties/performance_standards" - }, - "committed_metrics": { - "$ref": "/schemas/media-buy/package-request.json#/properties/committed_metrics" - }, - "creative_assignments": { - "$ref": "/schemas/media-buy/package-request.json#/properties/creative_assignments" - }, - "creatives": { - "$ref": "/schemas/media-buy/package-request.json#/properties/creatives" - }, - "agency_estimate_number": { - "$ref": "/schemas/media-buy/package-request.json#/properties/agency_estimate_number" - }, - "context": { - "$ref": "/schemas/media-buy/package-request.json#/properties/context" - }, - "ext": { - "$ref": "/schemas/media-buy/package-request.json#/properties/ext" - } - }, - "required": [ - "pricing_option_id", - "budget" - ], - "dependencies": { - "target_audiences": [ - "audience_evidence_requirements" - ], - "params": [ - "format_kind" - ] - }, - "not": { - "$ref": "/schemas/media-buy/package-request.json#/not" - }, - "additionalProperties": true -} diff --git a/static/schemas/source/media-buy/product-purchase.json b/static/schemas/source/media-buy/product-purchase.json index ee2c1765628..fadbc814edf 100644 --- a/static/schemas/source/media-buy/product-purchase.json +++ b/static/schemas/source/media-buy/product-purchase.json @@ -7,7 +7,6 @@ "x-adcp-validation": { "verifier_constraints": { "accepted_snapshot_terms": "Inside canonical-proposal.commercial_terms, each purchase MUST carry resolved start_time and end_time and MUST preserve every applicable measurement term and performance standard. Omission of measurement_terms or performance_standards means the accepted offer declared none.", - "price_adjustments_resolution": "When the option identified by pricing_option_id declares price_adjustments, pricing.fixed_price MUST equal the resolution of that option's table over this purchase's format_option_refs, placement selection and flight, and pricing.price_breakdown MUST record the declared adjustments followed by each fired row in declared order (a rate row as its rate when below 1, otherwise and for an amount row as its currency amount). The table itself is not embedded in the snapshot: pricing_option_id, covered by terms_digest, identifies exactly one immutable table.", "pricing_identity": { "pricing_option_id": "equals_pricing.pricing_option_id_when_pricing_present", "on_violation": "reject_before_commitment" diff --git a/static/schemas/source/pricing-options/cpc-option.json b/static/schemas/source/pricing-options/cpc-option.json index 2b673258c00..cb524f6271d 100644 --- a/static/schemas/source/pricing-options/cpc-option.json +++ b/static/schemas/source/pricing-options/cpc-option.json @@ -49,7 +49,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -60,6 +59,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/static/schemas/source/pricing-options/cpcv-option.json b/static/schemas/source/pricing-options/cpcv-option.json index 6ac5d12983d..a91958a62e2 100644 --- a/static/schemas/source/pricing-options/cpcv-option.json +++ b/static/schemas/source/pricing-options/cpcv-option.json @@ -49,7 +49,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -60,6 +59,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/static/schemas/source/pricing-options/cpm-option.json b/static/schemas/source/pricing-options/cpm-option.json index 3ca4f4442e6..1e34ccf2508 100644 --- a/static/schemas/source/pricing-options/cpm-option.json +++ b/static/schemas/source/pricing-options/cpm-option.json @@ -49,7 +49,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -60,6 +59,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/static/schemas/source/pricing-options/cpp-option.json b/static/schemas/source/pricing-options/cpp-option.json index 6a56c8c7e6d..c73cd1422f0 100644 --- a/static/schemas/source/pricing-options/cpp-option.json +++ b/static/schemas/source/pricing-options/cpp-option.json @@ -64,7 +64,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -75,6 +74,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency", "parameters"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/static/schemas/source/pricing-options/cpv-option.json b/static/schemas/source/pricing-options/cpv-option.json index ef41760e8d3..7a09fe80a3b 100644 --- a/static/schemas/source/pricing-options/cpv-option.json +++ b/static/schemas/source/pricing-options/cpv-option.json @@ -80,7 +80,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -91,6 +90,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency", "parameters"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/static/schemas/source/pricing-options/flat-rate-option.json b/static/schemas/source/pricing-options/flat-rate-option.json index 7fa05502a28..01f761d166d 100644 --- a/static/schemas/source/pricing-options/flat-rate-option.json +++ b/static/schemas/source/pricing-options/flat-rate-option.json @@ -110,7 +110,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -121,6 +120,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/static/schemas/source/pricing-options/price-adjustments.json b/static/schemas/source/pricing-options/price-adjustments.json deleted file mode 100644 index bb6d608e8f2..00000000000 --- a/static/schemas/source/pricing-options/price-adjustments.json +++ /dev/null @@ -1,238 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "/schemas/pricing-options/price-adjustments.json", - "title": "Price Adjustments", - "x-added-in": "3.3.0", - "description": "Optional ordered adjustment table on a binding fixed-price option; fixed_price is the base rate. A table and a fully priced seller offer have equal standing: a table tells the buyer it can compute the price locally for the selections and dates it covers; without one the price applies only to what was quoted, and yield-managed sellers are not expected to publish one. Composition is one running total in declared order: each firing row adds (fee) or subtracts (discount) round(running x rate) or its amount, so a 10% fee then a 10% fee is x1.21. An index factor f is a fee rate f - 1 or a discount rate 1 - f. Selection rows fire once per dimension (first applicable row); always rows each fire; valid_from/valid_until bound a row at the purchase start_time. A table applies only to the account it was returned for and expires with its quote (proposal or offer expires_at, or the discovery response's validity). Any change to the table mints a new pricing_option_id, so the accepted pricing_option_id (covered by terms_digest) identifies exactly one immutable table: changes the agreement already permits are priced from that table, which both parties retain from discovery and the seller MUST price from, not from a later table. The table grants no change rights; those come only from change_terms[]. Sellers MUST NOT return a table to callers below adcp_version 3.3. See pricing-models.mdx#selection-dependent-price-adjustments.", - "type": "array", - "items": { - "oneOf": [ - { - "type": "object", - "properties": { - "dimension": { - "type": "string", - "const": "format_option" - }, - "format_option_ref": { - "$ref": "/schemas/core/format-option-ref.json", - "description": "Matches when the purchase selects it." - }, - "kind": { - "type": "string", - "enum": [ - "fee", - "discount" - ], - "description": "fee adds to the running total, discount subtracts." - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 64 - }, - "rate": { - "type": "number", - "exclusiveMinimum": 0, - "description": "Proportion of the running total at this step; a fee rate may be 1 or more." - }, - "amount": { - "type": "number", - "exclusiveMinimum": 0, - "description": "Fixed amount per pricing unit." - }, - "valid_from": { - "type": "string", - "format": "date-time", - "description": "Inclusive window start." - }, - "valid_until": { - "type": "string", - "format": "date-time", - "description": "Exclusive window end." - }, - "ext": { - "$ref": "/schemas/core/ext.json" - } - }, - "required": [ - "dimension", - "format_option_ref", - "kind", - "name" - ], - "oneOf": [ - { - "required": [ - "rate" - ] - }, - { - "required": [ - "amount" - ] - } - ], - "additionalProperties": true - }, - { - "type": "object", - "properties": { - "dimension": { - "type": "string", - "const": "placement_selection" - }, - "placement_ref": { - "description": "Matches when the purchase selects it.", - "anyOf": [ - { - "allOf": [ - { - "$ref": "/schemas/core/placement-ref.json" - }, - { - "required": [ - "publisher_domain" - ] - } - ] - }, - { - "$ref": "/schemas/core/placement-identity.json" - } - ] - }, - "kind": { - "type": "string", - "enum": [ - "fee", - "discount" - ], - "description": "fee adds to the running total, discount subtracts." - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 64 - }, - "rate": { - "type": "number", - "exclusiveMinimum": 0, - "description": "Proportion of the running total at this step; a fee rate may be 1 or more." - }, - "amount": { - "type": "number", - "exclusiveMinimum": 0, - "description": "Fixed amount per pricing unit." - }, - "valid_from": { - "type": "string", - "format": "date-time", - "description": "Inclusive window start." - }, - "valid_until": { - "type": "string", - "format": "date-time", - "description": "Exclusive window end." - }, - "ext": { - "$ref": "/schemas/core/ext.json" - } - }, - "required": [ - "dimension", - "placement_ref", - "kind", - "name" - ], - "oneOf": [ - { - "required": [ - "rate" - ] - }, - { - "required": [ - "amount" - ] - } - ], - "additionalProperties": true - }, - { - "type": "object", - "properties": { - "dimension": { - "type": "string", - "const": "always" - }, - "kind": { - "type": "string", - "enum": [ - "fee", - "discount" - ], - "description": "fee adds to the running total, discount subtracts." - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 64 - }, - "rate": { - "type": "number", - "exclusiveMinimum": 0, - "description": "Proportion of the running total at this step; a fee rate may be 1 or more." - }, - "amount": { - "type": "number", - "exclusiveMinimum": 0, - "description": "Fixed amount per pricing unit." - }, - "valid_from": { - "type": "string", - "format": "date-time", - "description": "Inclusive window start." - }, - "valid_until": { - "type": "string", - "format": "date-time", - "description": "Exclusive window end." - }, - "ext": { - "$ref": "/schemas/core/ext.json" - } - }, - "required": [ - "dimension", - "kind", - "name" - ], - "oneOf": [ - { - "required": [ - "rate" - ] - }, - { - "required": [ - "amount" - ] - } - ], - "additionalProperties": true - } - ] - }, - "minItems": 1, - "maxItems": 20, - "x-adcp-validation": { - "verifier_constraints": { - "composition": "Rows apply sequentially to one running total in declared order; each step rounds half away from zero to price precision.", - "price_precision": "Greatest of the currency minor-unit exponent, 4 for cpm/vcpm/cpc/cpcv/cpv/cpp, and the fewest decimals exactly representing fixed_price and each amount, by numeric value.", - "flight_windows": "A flight crossing a row's valid_from or valid_until is rejected with INVALID_REQUEST.", - "resolved_price_binding": "A buyer-supplied pricing that differs from the resolved result MUST be rejected with INVALID_REQUEST carrying resolved_fixed_price and resolved_price_breakdown." - } - }, - "x-status": "experimental" -} diff --git a/static/schemas/source/pricing-options/price-breakdown.json b/static/schemas/source/pricing-options/price-breakdown.json index ab9aeac0842..124812b7d38 100644 --- a/static/schemas/source/pricing-options/price-breakdown.json +++ b/static/schemas/source/pricing-options/price-breakdown.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "/schemas/pricing-options/price-breakdown.json", "title": "Price Breakdown", - "description": "Breaks down how the buyer's effective price is composed from list_price. Adjustment kinds: fee and operator_fee increase the price, discount reduces it, and commission and settlement are disclosed without changing it. Invariant: list_price with fee, discount, and operator_fee adjustments applied in array order, rounded to currency precision at each step (or to the option's price precision when it declares price_adjustments, see price-adjustments.json, which can be finer), equals fixed_price when the parent object carries it; on auction-based packages the breakdown is informational. Sellers never emit operator_fee. The operator's buying platform adds it after every fee and discount; the running price before the first operator_fee is the seller's price, to which commission and settlement apply. Budgets are denominated at fixed_price, inclusive of commissions; a buying platform's budget toward the advertiser also includes operator fees.", + "description": "Breaks down how the buyer's effective price is composed from list_price. Adjustment kinds: fee and operator_fee increase the price, discount reduces it, and commission and settlement are disclosed without changing it. Invariant: list_price with fee, discount, and operator_fee adjustments applied in array order, rounded to currency precision at each step, equals fixed_price when the parent object carries it; on auction-based packages the breakdown is informational. Sellers never emit operator_fee. The operator's buying platform adds it after every fee and discount; the running price before the first operator_fee is the seller's price, to which commission and settlement apply. Budgets are denominated at fixed_price, inclusive of commissions; a buying platform's budget toward the advertiser also includes operator fees.", "type": "object", "properties": { "list_price": { diff --git a/static/schemas/source/pricing-options/vcpm-option.json b/static/schemas/source/pricing-options/vcpm-option.json index 432ddb88305..ee93ebba4f0 100644 --- a/static/schemas/source/pricing-options/vcpm-option.json +++ b/static/schemas/source/pricing-options/vcpm-option.json @@ -49,7 +49,6 @@ "description": "Breakdown of how fixed_price was derived from the list (rate card) price. Only meaningful when fixed_price is present.", "$ref": "/schemas/pricing-options/price-breakdown.json" }, - "price_adjustments": { "$ref": "/schemas/pricing-options/price-adjustments.json", "x-added-in": "3.3.0", "x-status": "experimental" }, "eligible_adjustments": { "type": "array", "description": "Adjustment kinds applicable to this pricing option. Tells buyer agents which adjustments are available before negotiation. When absent, no adjustments are pre-declared — the buyer should check price_breakdown if present.", @@ -60,6 +59,5 @@ } }, "required": ["pricing_option_id", "pricing_model", "currency"], - "dependencies": { "price_adjustments": ["fixed_price"] }, "additionalProperties": true } diff --git a/tests/assignment-landing-page.test.cjs b/tests/assignment-landing-page.test.cjs index f73fef91f6d..fc7b3b4e194 100644 --- a/tests/assignment-landing-page.test.cjs +++ b/tests/assignment-landing-page.test.cjs @@ -157,20 +157,28 @@ test('package create, update, and read assignments accept optional macro-bearing } }); -test('sync additive assignments and assign operations validate landing pages without creative upserts', async () => { +test('assign operations validate landing pages without creative upserts; deprecated assignments[] rows reject them', async () => { const validate = await compile(syncSchema); - for (const field of ['assignments', 'assignment_operations']) { - const assignment = { creative_id: 'hero', package_id: 'pkg_display' }; - if (field === 'assignment_operations') assignment.operation = 'assign'; - assert.equal(validate({ ...requestBase, [field]: [assignment] }), true, JSON.stringify(validate.errors)); - for (const landing_page_url of urls) { - assert.equal(validate({ ...requestBase, [field]: [{ ...assignment, landing_page_url }] }), true, - JSON.stringify(validate.errors)); - } - for (const landing_page_url of invalidUrls) { - assert.equal(validate({ ...requestBase, [field]: [{ ...assignment, landing_page_url }] }), false, field); - } + const assignment = { operation: 'assign', creative_id: 'hero', package_id: 'pkg_display' }; + assert.equal(validate({ ...requestBase, assignment_operations: [assignment] }), true, JSON.stringify(validate.errors)); + for (const landing_page_url of urls) { + assert.equal(validate({ ...requestBase, assignment_operations: [{ ...assignment, landing_page_url }] }), true, + JSON.stringify(validate.errors)); + } + for (const landing_page_url of invalidUrls) { + assert.equal(validate({ ...requestBase, assignment_operations: [{ ...assignment, landing_page_url }] }), false); } + // Withdrawn from the deprecated assignments[] row in 3.3 (adcp#8501). + const legacy = { creative_id: 'hero', package_id: 'pkg_display' }; + assert.equal(validate({ ...requestBase, assignments: [legacy] }), true, JSON.stringify(validate.errors)); + assert.equal(validate({ ...requestBase, assignments: [{ ...legacy, landing_page_url: urls[0] }] }), false, + 'the assignments[] row rejects landing_page_url by name; use assignment_operations assign'); + assert.equal(validate({ ...requestBase, assignments: [{ ...legacy, unrelated_extension: 'x' }] }), true, + 'the row is open: unrelated unknown keys are accepted'); + const legacyRow = syncSchema.properties.assignments.items; + assert.notEqual(legacyRow.additionalProperties, false); + assert.ok(legacyRow.not.anyOf.some(branch => branch.required?.includes('landing_page_url')), + 'the row not names landing_page_url'); for (const operation of ['unassign', 'replace']) { const assignment = { operation, creative_id: 'hero', package_id: 'pkg_display', landing_page_url: urls[0] }; if (operation === 'replace') assignment.replaces_creative_id = 'old_hero'; @@ -222,7 +230,6 @@ test('all input and readback fields use the creative click-through URL rules and const clickthroughUrl = readSchema('core/assets/url-asset.json').properties.url; for (const schema of [ readSchema('core/creative-assignment.json'), - syncSchema.properties.assignments.items, assignSchema, listAssignment, buyAssignment diff --git a/tests/assignment-trackers.test.cjs b/tests/assignment-trackers.test.cjs index eeb6f6dd40a..38cb21bd59b 100644 --- a/tests/assignment-trackers.test.cjs +++ b/tests/assignment-trackers.test.cjs @@ -39,11 +39,6 @@ const cases = [ packages: [{ package_id: 'pkg_display', creative_assignments: [{ creative_id: 'hero' }] }] }, row: data => data.packages[0].creative_assignments[0] }, - { - schema: 'creative/sync-creatives-request.json', write: true, - data: { ...requestBase, assignments: [{ ...assignment }] }, - row: data => data.assignments[0] - }, { schema: 'creative/sync-creatives-request.json', write: true, data: { ...requestBase, assignment_operations: [{ operation: 'assign', ...assignment }] }, @@ -134,6 +129,19 @@ test('sync supports multi-package assignment-only trafficking and atomic reset, } }); +test('deprecated assignments[] rows do not carry trackers (withdrawn from 3.3, adcp#8501)', async () => { + const validate = await compile('creative/sync-creatives-request.json'); + assert.equal(validate({ ...requestBase, assignments: [{ ...assignment }] }), true, JSON.stringify(validate.errors)); + assert.equal(validate({ ...requestBase, assignments: [{ ...assignment, trackers: [impression] }] }), false, + 'the assignments[] row rejects trackers by name; use assignment_operations assign'); + assert.equal(validate({ ...requestBase, assignments: [{ ...assignment, unrelated_extension: 'x' }] }), true, + 'the row is open: unrelated unknown keys are accepted'); + const row = readSchema('creative/sync-creatives-request.json').properties.assignments.items; + assert.equal(row.properties.trackers, undefined); + assert.notEqual(row.additionalProperties, false); + assert.ok(row.not.anyOf.some(branch => branch.required?.includes('trackers')), 'the row not names trackers'); +}); + test('unreleased assignment tracker documentation request validates against the source schema', async () => { const doc = fs.readFileSync(path.join(__dirname, '../docs/creative/task-reference/sync_creatives.mdx'), 'utf8'); const block = [...doc.matchAll(/```json\n([\s\S]*?)\n```/g)] diff --git a/tests/audience-evidence-targets.test.cjs b/tests/audience-evidence-targets.test.cjs index c674caacb0b..f08c67d45f5 100644 --- a/tests/audience-evidence-targets.test.cjs +++ b/tests/audience-evidence-targets.test.cjs @@ -117,14 +117,16 @@ describe('audience evidence target audiences (#8125)', () => { }); describe('schema', () => { - it('accepts target_audiences as a sibling of audience_evidence_requirements on discovery filters', () => { + it('no longer declares target_audiences on get_products discovery filters (withdrawn, adcp#8501)', () => { + const filters = readSchema('/schemas/core/product-filters.json'); + assert.equal(filters.properties.target_audiences, undefined); + assert.equal(filters.dependencies?.target_audiences, undefined); + assert.ok(filters.properties.audience_evidence_requirements, 'audience_evidence_requirements stays'); const requirements = { ...base, accepted_evidence_types: ['measured'], minimum_confidence: 0.8 }; - const filters = { audience_evidence_requirements: requirements, target_audiences: [target] }; - assert.equal(validateFilters(filters), true, JSON.stringify(validateFilters.errors)); + assert.equal(validateFilters({ audience_evidence_requirements: requirements }), true, JSON.stringify(validateFilters.errors)); }); it('requires the sibling audience_evidence_requirements', () => { - assert.equal(validateFilters({ target_audiences: [target] }), false); const packageRequest = clone(fixture.package_request); delete packageRequest.audience_evidence_requirements; packageRequest.target_audiences = [target]; @@ -164,7 +166,8 @@ describe('audience evidence target audiences (#8125)', () => { }); it('bounds the list and reuses the audience characteristic constraints', () => { - const filtersWith = target_audiences => validateFilters({ audience_evidence_requirements: base, target_audiences }); + // The discovery-filter copy is withdrawn; the bounds live on the package-level list. + const filtersWith = target_audiences => validatePackageRequest({ ...clone(fixture.package_request), audience_evidence_requirements: base, target_audiences }); assert.equal(filtersWith([]), false); assert.equal(filtersWith([target, target]), false); assert.equal(filtersWith(Array.from({ length: 11 }, (_, index) => ({ ...target, minimum_value: index / 10 }))), false); @@ -202,7 +205,7 @@ describe('audience evidence target audiences (#8125)', () => { const targetSchema = readSchema('/schemas/core/audience-evidence-target.json'); assert.equal(targetSchema['x-status'], 'experimental'); assert.equal(targetSchema['x-added-in'], '3.3.0'); - for (const uri of ['/schemas/core/product-filters.json', '/schemas/media-buy/package-request.json']) { + for (const uri of ['/schemas/media-buy/package-request.json']) { const property = readSchema(uri).properties.target_audiences; assert.equal(property['x-status'], 'experimental', uri); assert.equal(property['x-added-in'], '3.3.0', uri); @@ -228,9 +231,17 @@ describe('audience evidence target audiences (#8125)', () => { it('documents the surface under the heading the other pages link to', () => { const doc = fs.readFileSync(path.join(ROOT, 'docs/media-buy/task-reference/get_products.mdx'), 'utf8'); - assert.match(doc, /^#### Target audiences \(experimental\)$/m); - for (const page of ['docs/media-buy/product-discovery/media-products.mdx', 'docs/media-buy/task-reference/create_media_buy.mdx']) { - assert.match(fs.readFileSync(path.join(ROOT, page), 'utf8'), /get_products#target-audiences-experimental/, page); + assert.match(doc, /^#### Target audiences \(withdrawn\)$/m); + // Every link into the get_products target-audiences section resolves to an anchor on the page. + const anchors = new Set(['target-audiences-withdrawn']); + for (const match of doc.matchAll(/<\/a>/g)) anchors.add(match[1]); + const walk = dir => fs.readdirSync(dir, { withFileTypes: true }).flatMap(entry => (entry.isDirectory() + ? walk(path.join(dir, entry.name)) + : /\.mdx?$/.test(entry.name) ? [path.join(dir, entry.name)] : [])); + for (const file of walk(path.join(ROOT, 'docs'))) { + for (const match of fs.readFileSync(file, 'utf8').matchAll(/get_products#(target-audiences-[a-z-]+)/g)) { + assert.ok(anchors.has(match[1]), `${path.relative(ROOT, file)} links to missing anchor ${match[1]}`); + } } }); }); diff --git a/tests/collection-catalog.test.cjs b/tests/collection-catalog.test.cjs index 908ba99b5f8..4ed7bf65b54 100644 --- a/tests/collection-catalog.test.cjs +++ b/tests/collection-catalog.test.cjs @@ -206,7 +206,7 @@ test('docs carry the task page, the registry row, and no stale future-work note' for (const type of CARD_EVENTS) assert.ok(row.includes(type), `registry row names ${type}`); const guide = readText('docs/media-buy/product-discovery/collections-and-installments.mdx'); assert.doesNotMatch(guide, /is future work/); - for (const doc of ['docs/media-buy/task-reference/get_products.mdx', 'docs/media-buy/task-reference/list_products.mdx', 'docs/media-buy/product-discovery/collections-and-installments.mdx']) { + for (const doc of ['docs/media-buy/task-reference/list_products.mdx', 'docs/media-buy/product-discovery/collections-and-installments.mdx']) { assert.match(readText(doc), /collection_card\.\*/, `${doc} points webhook-fed mirrors at the card events`); } }); diff --git a/tests/execution-readiness.test.cjs b/tests/execution-readiness.test.cjs index dcade988a55..f49c448f039 100644 --- a/tests/execution-readiness.test.cjs +++ b/tests/execution-readiness.test.cjs @@ -39,9 +39,11 @@ const CONNECTION = { }, }; +// buy_products paths: readiness is read on list_products, whose next step is +// buy_products, not the legacy create_media_buy packages[] (adcp#8501). const ES_BINDING = - "packages[].optimization_goals[].event_sources[].event_source_id"; -const CATALOG_BINDING = "packages[].catalogs[]"; + "purchases[].optimization_goals[].event_sources[].event_source_id"; +const CATALOG_BINDING = "purchases[].catalog_ids[]"; const READY_EVENT_SOURCE = { requirement: EVENT_SOURCE, @@ -306,7 +308,7 @@ test("downstream_connection readiness derives from connection_state and has no c "no resolved resource for connections", ], [ - { ...connected, binding_field: "packages[].identity" }, + { ...connected, binding_field: "purchases[].identity" }, "connections have no binding field", ], [ @@ -358,9 +360,9 @@ test("product rollup is the first blocking state and is derivable", async () => ); }); -test("the readiness map rides on a public-scope response", async () => { +test("the readiness map rides on a public-scope list_products response", async () => { const validate = await compileSchema( - "/schemas/media-buy/get-products-response.json", + "/schemas/media-buy/list-products-response.json", ); const execution_readiness = { version: "er_7f3a", @@ -372,45 +374,17 @@ test("the readiness map rides on a public-scope response", async () => { }, }, }; + // list_products returns canonical (lightweight) products; the map is keyed by product_id. const product = { product_id: "social_conversions", name: "Social conversions", - description: "In-feed conversion placements.", - publisher_properties: [ - { publisher_domain: "social.example", selection_type: "all" }, - ], - delivery_type: "non_guaranteed", - format_ids: [ - { - agent_url: "https://creative.adcontextprotocol.org", - id: "display_300x250", - }, - ], - pricing_options: [ - { - pricing_option_id: "cpm_auction", - pricing_model: "cpm", - currency: "USD", - floor_price: 2, - }, - ], - reporting_capabilities: { - available_reporting_frequencies: ["daily"], - expected_delay_minutes: 60, - timezone: "UTC", - supports_webhooks: false, - available_metrics: ["impressions"], - date_range_support: "date_range", - }, - conversion_tracking: { action_sources: ["website"] }, - execution_requirements: [EVENT_SOURCE, CONNECTION], }; const base = { - adcp_version: "3.3", status: "completed", + outcome: "listed", products: [product], cache_scope: "public", - wholesale_feed_version: "wf_1", + feed_version: "feed_1", }; assert.equal( validate(base), @@ -442,23 +416,42 @@ test("the readiness map rides on a public-scope response", async () => { "a map entry needs requirements", ); - const schema = readJson("media-buy/get-products-response.json"); + assert.equal( + validate({ + status: "completed", + outcome: "unchanged", + cache_scope: "public", + feed_version: "feed_1", + execution_readiness, + }), + false, + "the map never rides on an unchanged outcome (it needs products)", + ); + + const schema = readJson("media-buy/list-products-response.json"); assert.ok( !schema.required?.includes("execution_readiness"), "the map is optional", ); + assert.deepEqual(schema.dependencies.execution_readiness, ["products"]); assert.equal( schema.properties.execution_readiness["x-status"], "experimental", ); }); -test("the request flag is optional, boolean, and experimental", async () => { +test("get_products no longer declares the readiness request flag or response map", () => { + const request = readJson("media-buy/get-products-request.json"); + const response = readJson("media-buy/get-products-response.json"); + assert.equal(request.properties.include_execution_readiness, undefined); + assert.equal(response.properties.execution_readiness, undefined); +}); + +test("the list_products request flag is optional, boolean, and experimental", async () => { const validate = await compileSchema( - "/schemas/media-buy/get-products-request.json", + "/schemas/media-buy/list-products-request.json", ); const request = { - buying_mode: "wholesale", account: { account_id: "acct_1" }, }; assert.equal(validate(request), true, validationMessage(validate)); @@ -471,8 +464,11 @@ test("the request flag is optional, boolean, and experimental", async () => { validate({ ...request, include_execution_readiness: "yes" }), false, ); - const schema = readJson("media-buy/get-products-request.json"); - assert.deepEqual(schema.required, ["buying_mode"]); + const schema = readJson("media-buy/list-products-request.json"); + assert.ok( + !schema.required?.includes("include_execution_readiness"), + "the flag is optional", + ); assert.equal( schema.properties.include_execution_readiness["x-status"], "experimental", diff --git a/tests/fast-channel-collections.test.cjs b/tests/fast-channel-collections.test.cjs index 960c06e39e0..2dc56d3a9b5 100644 --- a/tests/fast-channel-collections.test.cjs +++ b/tests/fast-channel-collections.test.cjs @@ -244,25 +244,6 @@ const responseCollection = { }; const selector = [{ publisher_domain: 'acmestreaming.example.com', collection_ids: ['pinnacle_challenge'] }]; const canonicalProduct = { product_id: 'pinnacle_video', name: 'Pinnacle Challenge video', collections: selector }; -const legacyProduct = { - product_id: 'pinnacle_video', - name: 'Pinnacle Challenge video', - description: 'Pre-roll on The Pinnacle Challenge', - publisher_properties: [{ publisher_domain: 'acmestreaming.example.com', selection_type: 'all' }], - format_ids: [{ agent_url: 'https://creative.example.com', id: 'video_30s' }], - delivery_type: 'guaranteed', - delivery_measurement: { provider: 'Test' }, - pricing_options: [{ pricing_option_id: 'cpm', pricing_model: 'cpm', rate: 10, currency: 'USD', is_fixed: true }], - reporting_capabilities: { - available_reporting_frequencies: ['daily'], - expected_delay_minutes: 240, - timezone: 'UTC', - supports_webhooks: false, - available_metrics: ['impressions'], - date_range_support: 'date_range', - }, - collections: selector, -}; const draftProposal = { proposal_id: 'proposal-1', name: 'Draft Pinnacle Challenge plan', @@ -284,7 +265,6 @@ const draftProposal = { terms_digest: `sha256:${'A'.repeat(43)}`, }; const responseCases = [ - ['/schemas/media-buy/get-products-response.json', { status: 'completed', products: [legacyProduct], cache_scope: 'public' }], ['/schemas/media-buy/list-products-response.json', { status: 'completed', outcome: 'listed', products: [canonicalProduct], feed_version: 'feed-v1', cache_scope: 'public' }], ['/schemas/media-buy/request-proposals-response.json', { status: 'completed', outcome: 'proposed', proposals: [draftProposal], products: [canonicalProduct] }], ['/schemas/media-buy/refine-proposals-response.json', { @@ -312,10 +292,6 @@ test('collections are forbidden on rejected and unchanged outcomes', async () => const rejected = { status: 'completed', outcome: 'rejected', reason: 'No available offer satisfies the campaign constraints.' }; assert.equal(proposals(rejected), true, JSON.stringify(proposals.errors, null, 2)); assert.equal(proposals({ ...rejected, collections: [responseCollection] }), false); - const products = await compile('/schemas/media-buy/get-products-response.json'); - const declined = { status: 'rejected', reason: 'Budget is below the minimum for this inventory.' }; - assert.equal(products(declined), true, JSON.stringify(products.errors, null, 2)); - assert.equal(products({ ...declined, collections: [responseCollection] }), false); const listed = await compile('/schemas/media-buy/list-products-response.json'); const unchanged = { status: 'completed', outcome: 'unchanged', feed_version: 'feed-v1', cache_scope: 'public' }; assert.equal(listed(unchanged), true, JSON.stringify(listed.errors, null, 2)); @@ -362,7 +338,6 @@ test('response collection fields are experimental and added in 3.3.0', () => { const fields = [ read('core/collection.json').properties.url, read('core/response-collection.json'), - read('media-buy/get-products-response.json').properties.collections, read('media-buy/list-products-response.json').properties.collections, read('media-buy/request-proposals-response.json').properties.collections, read('media-buy/refine-proposals-response.json').properties.collections, @@ -373,7 +348,7 @@ test('response collection fields are experimental and added in 3.3.0', () => { assert.equal(field['x-status'], 'experimental'); assert.equal(field['x-added-in'], '3.3.0'); } - for (const file of ['get-products', 'list-products', 'request-proposals', 'refine-proposals']) { + for (const file of ['list-products', 'request-proposals', 'refine-proposals']) { const schema = read(`media-buy/${file}-response.json`); assert.equal(schema.properties.collections.items.$ref, '/schemas/core/response-collection.json'); assert.deepEqual(schema.dependencies.collections, ['products']); @@ -387,7 +362,6 @@ test('response collection fields are experimental and added in 3.3.0', () => { const ACCEPTS_UNKNOWN_FIELDS = /This request accepts unknown fields/; const CLOSED_IN_3_2 = /The 3\.2 schema of this request rejects unknown fields/; const requestCases = [ - ['/schemas/media-buy/get-products-request.json', { buying_mode: 'brief', brief: 'Creator video for a running shoe launch' }, ACCEPTS_UNKNOWN_FIELDS], ['/schemas/media-buy/list-products-request.json', { brand: { domain: 'nova-brands.example' } }, CLOSED_IN_3_2], ['/schemas/media-buy/request-proposals-request.json', { idempotency_key: 'req-proposals-0001', @@ -420,7 +394,7 @@ for (const [schemaId, base, unknownFieldPhrasing] of requestCases) { test('response collections descriptions carry the opt-in and the closed freshness list', () => { const read = (file) => JSON.parse(fs.readFileSync(path.join(SCHEMA_BASE_DIR, file), 'utf8')); - for (const file of ['get-products', 'list-products', 'request-proposals', 'refine-proposals']) { + for (const file of ['list-products', 'request-proposals', 'refine-proposals']) { const desc = read(`media-buy/${file}-response.json`).properties.collections.description; assert.match(desc, /unless the request set include_collections to true/, file); assert.match(desc, /only on images, sample_content, url, description, season, cadence and distribution\[\]\.followers/, file); @@ -486,16 +460,33 @@ test('brand-side collection links use their own experimental feature id', () => assert.match(row('brand.collection_links'), /get_brand_identity/); }); -test('include_collections is part of the feed version scope', () => { +test('get_products no longer declares include_collections or collections (adcp#8501)', async () => { + const read = (file) => JSON.parse(fs.readFileSync(path.join(SCHEMA_BASE_DIR, file), 'utf8')); + const request = read('media-buy/get-products-request.json'); + const response = read('media-buy/get-products-response.json'); + assert.equal(request.properties.include_collections, undefined); + assert.equal(response.properties.collections, undefined); + assert.equal(response.dependencies?.collections, undefined); + const rejected = read('media-buy/get-products-rejected.json'); + assert.equal(rejected.properties.collections, undefined); + const tuple = /include_collections/; + assert.doesNotMatch(request.properties.if_wholesale_feed_version.description, tuple); + assert.doesNotMatch(response.properties.wholesale_feed_version.description, tuple); + // The flag stays advertised on every other discovery surface. + for (const file of ['list-products-request', 'request-proposals-request', 'refine-proposals-request']) { + assert.ok(read(`media-buy/${file}.json`).properties.include_collections, `${file} keeps include_collections`); + } + // A caller that still sends the flag is not rejected by the schema: the request accepts unknown fields. + const validate = await compile('/schemas/media-buy/get-products-request.json'); + assert.equal(validate({ buying_mode: 'brief', brief: 'Creator video', include_collections: true }), true, JSON.stringify(validate.errors, null, 2)); +}); + +test('include_collections is part of the feed version scope on list_products', () => { const read = (file) => JSON.parse(fs.readFileSync(path.join(SCHEMA_BASE_DIR, file), 'utf8')); - const tuple = /deprecated property_list, catalog, include_collections\) for cache_scope: 'public'/; - assert.match(read('media-buy/get-products-request.json').properties.if_wholesale_feed_version.description, tuple); - assert.match(read('media-buy/get-products-response.json').properties.wholesale_feed_version.description, tuple); assert.match(read('media-buy/list-products-request.json').properties.if_feed_version.description, /include_collections is part of the selection/); assert.match(read('media-buy/list-products-response.json').properties.feed_version.description, /including include_collections/); const doc = fs.readFileSync(path.join(__dirname, '../docs/media-buy/task-reference/get_products.mdx'), 'utf8'); - assert.ok(doc.includes('| Public | `(agent, buying_mode, filters, targeting_overlay, media_buy_frequency_cap, required_overlay_support, required_media_buy_support, deprecated property_list, catalog, include_collections)` |')); - assert.ok(doc.includes('deprecated property_list, catalog, include_collections, account_id)` |')); + assert.doesNotMatch(doc, /include_collections/, 'get_products reference no longer documents include_collections'); const guide = fs.readFileSync(path.join(__dirname, '../docs/media-buy/product-discovery/collections-and-installments.mdx'), 'utf8'); assert.doesNotMatch(guide, /does not grow a new key/); assert.match(guide, /`include_collections` is part of the version scope/); diff --git a/tests/get-products-deprecated-withdrawals.test.cjs b/tests/get-products-deprecated-withdrawals.test.cjs new file mode 100644 index 00000000000..65445279b67 --- /dev/null +++ b/tests/get-products-deprecated-withdrawals.test.cjs @@ -0,0 +1,168 @@ +/** + * Contract test for the fields withdrawn from the deprecated get_products + * facade and the price_adjustments table withdrawn to 4.0 (adcp#8501). + * + * get_products is deprecated for new integrations in 3.2, so 3.3 does not grow + * it. The experimental refine[].package, include_collections / collections, + * include_execution_readiness / execution_readiness, filters.target_audiences + * and refinement_applied resolution fields leave its schemas; the readiness + * flag and map live on list_products, and collections stay on list_products, + * request_proposals and refine_proposals. The experimental price_adjustments + * table leaves every pricing option. sync_creatives assignments[] rows lose + * trackers and landing_page_url; assignment_operations assign keeps both. This + * test fails if any withdrawn field returns, and checks the 4.0 registry says + * where the designs went. + */ +'use strict'; + +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const test = require('node:test'); +const yaml = require('js-yaml'); +const Ajv = require('ajv'); +const addFormats = require('ajv-formats'); + +const ROOT = path.join(__dirname, '..'); +const SCHEMAS = path.join(ROOT, 'static/schemas/source'); +const readSchema = (relative) => JSON.parse(fs.readFileSync(path.join(SCHEMAS, relative), 'utf8')); +const exists = (relative) => fs.existsSync(path.join(SCHEMAS, relative)); +const registryChecks = () => { + const registry = yaml.load(fs.readFileSync(path.join(ROOT, 'static/compliance/source/universal/v4-compatibility.yaml'), 'utf8')); + const list = registry.checks ?? registry.items ?? Object.values(registry).find(Array.isArray); + assert.ok(Array.isArray(list), 'the registry lists its checks'); + return list; +}; + +const ajv = new Ajv({ + allErrors: true, strict: false, discriminator: true, + loadSchema: async (uri) => readSchema(uri.replace('/schemas/', '')), +}); +addFormats(ajv); + +const PRICING_OPTIONS = ['cpm', 'vcpm', 'cpc', 'cpcv', 'cpv', 'cpp', 'flat-rate']; + +test('get_products request no longer declares the withdrawn fields', () => { + const request = readSchema('media-buy/get-products-request.json'); + assert.equal(request.properties.include_collections, undefined); + assert.equal(request.properties.include_execution_readiness, undefined); + + const refine = request.properties.refine.items; + const scopes = refine.oneOf.map((arm) => arm.properties.scope.const); + assert.deepEqual(scopes, ['request', 'product', 'proposal'], 'refine[].package is withdrawn'); + assert.equal(JSON.stringify(refine).includes('package-forecast-input'), false); + + const filters = readSchema('core/product-filters.json'); + assert.equal(filters.properties.target_audiences, undefined); + assert.equal(filters.dependencies?.target_audiences, undefined); +}); + +test('refine[].package is rejected by name on every scope', async () => { + const validate = await ajv.compileAsync(readSchema('media-buy/get-products-request.json')); + const base = { + buying_mode: 'refine', + refine: [{ scope: 'product', product_id: 'prod_display', ask: 'more reach' }], + }; + assert.equal(validate(base), true, JSON.stringify(validate.errors)); + assert.equal(validate({ ...base, refine: [{ ...base.refine[0], package: {} }] }), false, + 'a product-scoped entry rejects package'); + + for (const arm of readSchema('media-buy/get-products-request.json').properties.refine.items.oneOf) { + const names = (arm.not?.anyOf ?? [arm.not]).flatMap((branch) => branch?.required ?? []); + assert.ok(names.includes('package'), `${arm.properties.scope.const} scope rejects package by name`); + } +}); + +test('get_products response and rejection no longer declare the withdrawn fields', () => { + const response = readSchema('media-buy/get-products-response.json'); + assert.equal(response.properties.collections, undefined); + assert.equal(response.properties.execution_readiness, undefined); + assert.equal(response.dependencies?.collections, undefined); + assert.equal(response.dependencies?.execution_readiness, undefined); + + for (const arm of response.properties.refinement_applied.items.oneOf) { + for (const field of ['result_product_id', 'resolved_start_time', 'resolved_end_time']) { + assert.equal(arm.properties[field], undefined, `refinement_applied ${field}`); + } + } + + const rejected = readSchema('media-buy/get-products-rejected.json'); + assert.equal(rejected.properties.collections, undefined); +}); + +test('the withdrawn files are deleted', () => { + for (const file of [ + 'media-buy/package-forecast-input.json', + 'pricing-options/price-adjustments.json', + 'error-details/price-adjustments-mismatch.json', + ]) { + assert.equal(exists(file), false, `${file} is withdrawn`); + } + assert.equal( + fs.existsSync(path.join(ROOT, 'static/compliance/source/test-vectors/price-adjustments')), + false, + 'the price_adjustments test vectors are withdrawn', + ); + assert.equal(fs.existsSync(path.join(ROOT, 'tests/price-adjustments-vectors.test.cjs')), false); +}); + +test('list_products carries the execution readiness flag and map as experimental', () => { + const request = readSchema('media-buy/list-products-request.json'); + const flag = request.properties.include_execution_readiness; + assert.ok(flag, 'list_products takes include_execution_readiness'); + assert.equal(flag['x-status'], 'experimental'); + assert.equal(flag.type, 'boolean'); + + const response = readSchema('media-buy/list-products-response.json'); + const map = response.properties.execution_readiness; + assert.ok(map, 'list_products returns execution_readiness'); + assert.equal(map['x-status'], 'experimental'); + assert.deepEqual(response.dependencies.execution_readiness, ['products'], 'never on an unchanged outcome'); +}); + +test('collections stay on list_products, request_proposals and refine_proposals', () => { + for (const file of ['list-products', 'request-proposals', 'refine-proposals']) { + assert.ok(readSchema(`media-buy/${file}-response.json`).properties.collections, `${file} response keeps collections`); + assert.ok(readSchema(`media-buy/${file}-request.json`).properties.include_collections, `${file} request keeps include_collections`); + } +}); + +test('no pricing option declares price_adjustments', () => { + for (const option of PRICING_OPTIONS) { + const file = `pricing-options/${option}-option.json`; + const schema = readSchema(file); + assert.equal(schema.properties.price_adjustments, undefined, file); + assert.equal(schema.dependencies?.price_adjustments, undefined, file); + assert.equal(JSON.stringify(schema).includes('price_adjustments'), false, `${file} still mentions price_adjustments`); + } + assert.equal( + JSON.stringify(readSchema('core/product.json')).includes('price_adjustments'), + false, + 'product.json no longer ties price_adjustments rows to overlay_support', + ); +}); + +test('sync_creatives assignments[] rows no longer carry trackers or landing_page_url', () => { + const request = readSchema('creative/sync-creatives-request.json'); + const row = request.properties.assignments.items; + const rejected = row.not.anyOf.flatMap((branch) => branch.required ?? []); + assert.ok(rejected.includes('trackers') && rejected.includes('landing_page_url'), + 'the legacy row rejects both names'); + assert.equal(row.properties.trackers, undefined); + assert.equal(row.properties.landing_page_url, undefined); + + const assign = request.properties.assignment_operations.items.oneOf + .find((arm) => arm.properties.operation?.const === 'assign'); + assert.ok(assign, 'assignment_operations keeps an assign arm'); + assert.ok(assign.properties.trackers, 'assign keeps trackers'); + assert.ok(assign.properties.landing_page_url, 'assign keeps landing_page_url'); +}); + +test('the 4.0 registry says where the withdrawn designs went', () => { + const checks = new Map(registryChecks().map((check) => [String(check.id), check])); + assert.ok(checks.has('canonical_price_adjustments_required_in_4_0'), 'a price_adjustments entry'); + // filters.target_audiences is covered by the purchase-path entry, whose fix says it left get_products. + const targets = checks.get('purchase_target_audiences_required_in_4_0'); + assert.ok(targets, 'the target_audiences entry'); + assert.match(String(targets.fix), /get_products/); +}); diff --git a/tests/mcp-schema-projection.test.cjs b/tests/mcp-schema-projection.test.cjs index 2df009d6e40..16792db8b4c 100644 --- a/tests/mcp-schema-projection.test.cjs +++ b/tests/mcp-schema-projection.test.cjs @@ -1665,7 +1665,6 @@ test('rewriteEmbeddedResourceRefs unit: root-$id collision causes projection to for (const [relativePath, expectedDefinition] of [ ['compliance/comply-test-controller-request.json', 'external:core/product.json'], - ['media-buy/get-products-request.json', 'external:media-buy/package-forecast-input.json'], ['media-buy/get-products-response.json', 'external:core/product.json'], ]) { test(`${relativePath} uses embedded-resource refs without long root-anchored pointers`, () => { diff --git a/tests/price-adjustments-vectors.test.cjs b/tests/price-adjustments-vectors.test.cjs deleted file mode 100644 index 76c49f0ad9a..00000000000 --- a/tests/price-adjustments-vectors.test.cjs +++ /dev/null @@ -1,392 +0,0 @@ -/** - * Validates the price_adjustments resolution vectors in - * static/compliance/source/test-vectors/price-adjustments/vectors.json. - * - * Layers: - * 1. Every declared option validates against pricing-option.json (product - * offer). The accepted snapshot is the same option without the table - * (canonical-pricing-option.json is closed, so it carries no table). - * 2. A reference resolver implementing the normative sequential rule (one - * running total, each firing row applied in declared order) reproduces - * every resolved price, ordered application, and fired-row amount in exact - * integer arithmetic at the option's price precision. - * 3. The resolved snapshot (resolved fixed_price, price_breakdown of fired - * rows, no embedded table) validates against canonical-pricing-option.json - * and folds back to fixed_price per the price-breakdown invariant. - * 4. Negative schema cases are rejected and the changed-table identity rule - * holds. - * 5. A table is bound to its quote (account and expiry), and the accepted - * terms price a change the agreement already permits from the table of the - * accepted pricing_option_id, without granting any change right. - * - * SDKs consume the same vector file to check their own resolvers. - */ -const fs = require('node:fs'); -const path = require('node:path'); -const test = require('node:test'); -const assert = require('node:assert/strict'); -const Ajv = require('ajv'); -const addFormats = require('ajv-formats'); - -const REPO_ROOT = path.join(__dirname, '..'); -const SCHEMA_ROOT = path.join(REPO_ROOT, 'static', 'schemas', 'source'); -const vectors = JSON.parse( - fs.readFileSync( - path.join(REPO_ROOT, 'static', 'compliance', 'source', 'test-vectors', 'price-adjustments', 'vectors.json'), - 'utf8', - ), -); - -function loadSchemaUri(uri) { - if (!uri.startsWith('/schemas/')) throw new Error(`Unexpected schema URI: ${uri}`); - return JSON.parse(fs.readFileSync(path.join(SCHEMA_ROOT, uri.slice('/schemas/'.length)), 'utf8')); -} - -async function compile(uri) { - const ajv = new Ajv({ allErrors: true, strict: false, discriminator: true, loadSchema: loadSchemaUri }); - addFormats(ajv); - return ajv.compileAsync(loadSchemaUri(uri)); -} - -// --- Reference resolver (the normative rule, in exact integer arithmetic) ----- - -const PER_UNIT_MODELS = new Set(['cpm', 'vcpm', 'cpc', 'cpcv', 'cpv', 'cpp']); - -// Exact decimal parse of a JSON number by value, never by lexical form: -// trailing zeros and exponent notation do not change the result. -function parseDecimal(n) { - const m = /^(-?)(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?$/i.exec(String(n)); - assert.ok(m, `unparseable number ${n}`); - const frac = (m[3] || '').replace(/0+$/, ''); - const scale = frac.length - Number(m[4] || 0); - const digits = BigInt(m[2] + frac); - return scale >= 0 ? { int: digits, scale } : { int: digits * 10n ** BigInt(-scale), scale: 0 }; -} - -// Fewest decimal places that exactly represent the value. -function decimalPlaces(n) { - const { int, scale } = parseDecimal(n); - let places = scale; - let rest = int; - while (places > 0 && rest % 10n === 0n) { - rest /= 10n; - places -= 1; - } - return places; -} - -function minorExponent(currency) { - const e = vectors.currency_minor_unit_exponent[currency]; - assert.notEqual(e, undefined, `vector currency ${currency} needs an exponent`); - return e; -} - -// Price precision: the greatest of the currency minor-unit exponent, 4 for -// per-unit models, and the decimals that exactly represent fixed_price and each -// row amount. -function pricePrecision(option) { - const places = [minorExponent(option.currency), decimalPlaces(option.fixed_price)]; - if (PER_UNIT_MODELS.has(option.pricing_model)) places.push(4); - for (const row of option.price_adjustments || []) { - if (row.amount !== undefined) places.push(decimalPlaces(row.amount)); - } - return Math.max(...places); -} - -function toScaled(amount, precision) { - const { int, scale } = parseDecimal(amount); - assert.ok(scale <= precision, `${amount} needs more than ${precision} decimals`); - return int * 10n ** BigInt(precision - scale); -} - -function toNumber(scaled, precision) { - return Number(scaled) / 10 ** precision; -} - -function divRoundHalfAwayFromZero(n, d) { - const negative = n < 0n; - const an = negative ? -n : n; - const q = (2n * an + d) / (2n * d); - return negative ? -q : q; -} - -// round half away from zero of running x proportion, where the proportion is -// the exact decimal num/10^scale. -function proportionOf(running, proportion) { - const { int, scale } = parseDecimal(proportion); - return divRoundHalfAwayFromZero(running * int, 10n ** BigInt(scale)); -} - -// Full-identity keys, so different encodings of one value compare equal and the -// same ID under a different scope does not. -function formatKey(ref) { - return ref.scope === 'publisher' ? `p:${ref.publisher_domain}:${ref.format_option_id}` : `l:${ref.format_option_id}`; -} - -// A seller agent is identified by its URL, compared under the AdCP URL -// canonicalization rules (docs/reference/url-canonicalization), not byte equality: -// scheme and host lowercased, default port and userinfo stripped, empty path "/", -// dot segments removed, fragment dropped. -function canonicalAgentUrl(value) { - const url = new URL(value); - url.username = ''; - url.password = ''; - url.hash = ''; - return url.href; -} - -function placementKey(ref) { - return ref.kind === 'seller_inline' - ? `s:${canonicalAgentUrl(ref.seller_agent.agent_url)}:${ref.placement_id}` - : `p:${ref.publisher_domain}:${ref.placement_id}`; -} - -function selectedKeys(selection) { - const placements = selection.placement_selection; - return { - format_option: new Set((selection.format_option_refs || []).map(formatKey)), - placement_selection: new Set( - placements && placements.mode === 'selected' ? placements.placement_refs.map(placementKey) : [], - ), - }; -} - -function rowKey(row) { - return row.dimension === 'format_option' ? formatKey(row.format_option_ref) : placementKey(row.placement_ref); -} - -function rowMatches(row, selected) { - return row.dimension === 'always' || selected[row.dimension].has(rowKey(row)); -} - -function inWindow(row, at) { - if (row.valid_from === undefined && row.valid_until === undefined) return true; - assert.ok(at !== undefined, `row ${row.name} has a window but the case has no flight`); - return ( - (row.valid_from === undefined || at >= Date.parse(row.valid_from)) && - (row.valid_until === undefined || at < Date.parse(row.valid_until)) - ); -} - -// A flight [start, end) that crosses a window boundary of a row that would -// otherwise apply is rejected; the buyer splits it. -function crossesBoundary(option, selection) { - if (!selection.flight) return false; - const start = Date.parse(selection.flight.start_time); - const end = Date.parse(selection.flight.end_time); - const selected = selectedKeys(selection); - return (option.price_adjustments || []).some(row => { - if (!rowMatches(row, selected)) return false; - return [row.valid_from, row.valid_until].some(edge => { - if (edge === undefined) return false; - const t = Date.parse(edge); - return t > start && t < end; - }); - }); -} - -// Declared order; first valid matching row per selection dimension, every valid -// always row. -function firingRows(option, selection) { - const at = selection.flight ? Date.parse(selection.flight.start_time) : undefined; - const selected = selectedKeys(selection); - const fired = new Set(); - const winners = []; - for (const row of option.price_adjustments || []) { - if (!inWindow(row, at) || !rowMatches(row, selected)) continue; - if (row.dimension !== 'always') { - if (fired.has(row.dimension)) continue; - fired.add(row.dimension); - } - winners.push(row); - } - return winners; -} - -function resolve(option, selection) { - if (crossesBoundary(option, selection)) return { error: 'flight_spans_validity_boundary' }; - const precision = pricePrecision(option); - const rows = firingRows(option, selection); - const entries = []; - - // One running total; each firing row applies to it in declared order. A rate - // row adds or subtracts round(running x rate), an amount row its amount. - let running = toScaled(option.fixed_price, precision); - for (const row of rows) { - const delta = row.amount !== undefined ? toScaled(row.amount, precision) : proportionOf(running, row.rate); - running += row.kind === 'fee' ? delta : -delta; - if (delta === 0n) continue; // contributes nothing, omitted from the breakdown - // Recorded as its rate when below 1 (the breakdown schema bound), otherwise as its currency delta. - const entry = { kind: row.kind, name: row.name }; - if (row.rate !== undefined && Number(row.rate) < 1) entry.rate = row.rate; - else entry.amount = toNumber(delta, precision); - entries.push(entry); - } - if (running < 0n) return { error: 'below_zero' }; - return { rows, entries, precision, fixed_price: toNumber(running, precision) }; -} - -// The accepted snapshot records each fired row as its own price_breakdown entry -// after the declared adjustments. -function resolvedSnapshot(option, result) { - const { price_adjustments: _table, ...rest } = option; - const snapshot = { ...rest, fixed_price: result.fixed_price }; - if (!result.entries.length) return snapshot; - const declared = option.price_breakdown; - snapshot.price_breakdown = { - list_price: declared ? declared.list_price : option.fixed_price, - adjustments: [...(declared ? declared.adjustments : []), ...result.entries], - }; - return snapshot; -} - -// The price-breakdown invariant: fold list_price through every adjustment. -function foldBreakdown(breakdown, precision) { - let running = toScaled(breakdown.list_price, precision); - for (const adjustment of breakdown.adjustments) { - const sign = adjustment.kind === 'fee' ? 1n : -1n; - running += - sign * - (adjustment.amount !== undefined ? toScaled(adjustment.amount, precision) : proportionOf(running, adjustment.rate)); - } - return running; -} - -// --- Tests ------------------------------------------------------------------- - -test('every declared option validates as a product pricing option; the closed canonical snapshot carries no table', async () => { - const [validateOffer, validateCanonical] = await Promise.all([ - compile('/schemas/core/pricing-option.json'), - compile('/schemas/core/canonical-pricing-option.json'), - ]); - for (const [name, option] of Object.entries(vectors.options)) { - assert.ok(validateOffer(option), `${name} as offer: ${JSON.stringify(validateOffer.errors)}`); - assert.equal(validateCanonical(option), false, `${name}: canonical snapshot must not embed the table`); - } -}); - -test('resolution cases reproduce the resolved price and ordered application', async () => { - const validateCanonical = await compile('/schemas/core/canonical-pricing-option.json'); - for (const c of vectors.resolution_cases) { - const option = vectors.options[c.option]; - const result = resolve(option, c.selection); - assert.equal(result.error, undefined, `${c.id}: ${result.error}`); - assert.equal(result.fixed_price, c.expect.fixed_price, `${c.id}: fixed_price`); - assert.deepEqual( - result.rows.map(row => row.name), - c.expect.applied, - `${c.id}: applied rows`, - ); - assert.deepEqual(result.entries, c.expect.breakdown, `${c.id}: price_breakdown rows`); - - const snapshot = resolvedSnapshot(option, result); - assert.ok(validateCanonical(snapshot), `${c.id}: snapshot ${JSON.stringify(validateCanonical.errors)}`); - if (snapshot.price_breakdown) { - const folded = foldBreakdown(snapshot.price_breakdown, result.precision); - assert.equal(toNumber(folded, result.precision), snapshot.fixed_price, `${c.id}: breakdown invariant`); - assert.equal( - snapshot.price_breakdown.list_price, - option.price_breakdown ? option.price_breakdown.list_price : option.fixed_price, - `${c.id}: list_price is the base the verifier re-resolves from`, - ); - } else { - assert.equal(snapshot.fixed_price, option.fixed_price, `${c.id}: no row fired, base rate`); - } - } -}); - -test('precision is defined by numeric value, not lexical form', () => { - assert.equal(decimalPlaces(JSON.parse('0.0100')), 2); - assert.equal(decimalPlaces(JSON.parse('20.00')), 0); - assert.equal(decimalPlaces(1e-7), 7); - assert.equal(decimalPlaces(1.5e-7), 8); - assert.equal(decimalPlaces(0.00125), 5); - assert.equal(decimalPlaces(1000), 0); -}); - -test('purchases with no valid resolution are rejected, never clamped', () => { - for (const c of vectors.invalid_resolution_cases) { - assert.equal(resolve(vectors.options[c.option], c.selection).error, c.expect_error, c.id); - assert.equal(c.expect_outcome, 'INVALID_REQUEST'); - } -}); - -test('buyer-supplied pricing must equal the resolved result', () => { - for (const c of vectors.buyer_supplied_pricing_cases) { - const result = resolve(vectors.options[c.option], c.selection); - const outcome = result.fixed_price === c.supplied_fixed_price ? 'accepted' : 'INVALID_REQUEST'; - assert.equal(outcome, c.expect, c.id); - if (c.error_field) { - assert.match(c.error_field, /^pricing\./); - assert.equal(result.fixed_price, c.resolved_fixed_price, `${c.id}: resolved value carried in error details`); - assert.deepEqual(result.entries, c.resolved_breakdown, `${c.id}: resolved breakdown carried in error details`); - } - } -}); - -test('a changed table requires a distinct pricing_option_id', () => { - for (const c of vectors.identity_cases) { - const previous = vectors.options[c.previous]; - const current = vectors.options[c.current]; - assert.notDeepEqual(previous.price_adjustments, current.price_adjustments, c.id); - assert.notEqual(previous.pricing_option_id, current.pricing_option_id, c.id); - } -}); - -test('schema negative cases are rejected', async () => { - const validateOffer = await compile('/schemas/core/pricing-option.json'); - for (const c of vectors.schema_negative_cases) { - const option = { ...vectors.options.cpm_rate_card }; - for (const [key, value] of Object.entries(c.mutate)) { - if (value === null) delete option[key]; - else option[key] = value; - } - assert.equal(validateOffer(option), false, `${c.id} should be invalid as an offer`); - } -}); - -// A table is bound to its quote: the account it was returned for, until the -// quote (proposal, offer, or discovery response) expires. -function tableApplies(quote, use) { - return use.account_id === quote.account_id && Date.parse(use.at) < Date.parse(quote.expires_at); -} - -test('a table applies only to the quoted account and expires with the quote', () => { - for (const c of vectors.quote_binding_cases) { - assert.equal(tableApplies(c.quote, c.use) ? 'table_applies' : 'table_does_not_apply', c.expect, c.id); - } -}); - -// A changed table is a new pricing_option_id, so the accepted pricing_option_id -// identifies exactly one immutable table. A change the agreement already permits -// is priced from that table, never from a later one, without a re-quote. The -// table itself grants no change right: permission comes only from change_terms[]. -function priceAcceptedChange(option, c) { - if (!c.change_permitted_by_change_terms) return { outcome: 'ACTION_NOT_ALLOWED' }; - return { outcome: 'priced', fixed_price: resolve(option, c.requested_selection).fixed_price }; -} - -test('accepted terms price a permitted change from the accepted option\'s table and grant no change right', () => { - for (const c of vectors.accepted_terms_cases) { - assert.deepEqual(priceAcceptedChange(vectors.options[c.option], c), c.expect, c.id); - if (c.later_option) { - const later = vectors.options[c.later_option]; - assert.notEqual(later.pricing_option_id, vectors.options[c.option].pricing_option_id, c.id); - assert.notEqual(resolve(later, c.requested_selection).fixed_price, c.expect.fixed_price, `${c.id}: later table prices differently`); - } - } -}); - -test('order of rows is the order of application', () => { - const [ratesThenAmount, amountThenRates] = [vectors.options.cpm_placement_first, vectors.options.cpm_rate_card]; - const selection = { - format_option_refs: [{ scope: 'product', format_option_id: 'video_30s' }], - placement_selection: { - mode: 'selected', - placement_refs: [{ publisher_domain: 'streamhaus.example', placement_id: 'premium_home' }], - }, - }; - // 20 x 1.15 + 2 = 25.00 versus (20 + 2) x 1.15 = 25.30: the same two rows, declared in the other order. - assert.equal(resolve(ratesThenAmount, selection).fixed_price, 25); - assert.equal(resolve(amountThenRates, selection).fixed_price, 25.3); -}); diff --git a/tests/structured-package-refine.test.cjs b/tests/structured-package-refine.test.cjs deleted file mode 100644 index 621cee119d4..00000000000 --- a/tests/structured-package-refine.test.cjs +++ /dev/null @@ -1,284 +0,0 @@ -const assert = require('node:assert/strict'); -const fs = require('node:fs'); -const path = require('node:path'); -const { before, test } = require('node:test'); -const Ajv = require('ajv'); -const addFormats = require('ajv-formats'); - -const SCHEMAS = path.join(__dirname, '../static/schemas/source'); -const PACKAGE_URI = '/schemas/media-buy/package-request.json'; -const FORECAST_URI = '/schemas/media-buy/package-forecast-input.json'; -const REQUEST_URI = '/schemas/media-buy/get-products-request.json'; -const RESPONSE_URI = '/schemas/media-buy/get-products-response.json'; -const CREATE_URI = '/schemas/media-buy/create-media-buy-request.json'; -const read = (uri) => JSON.parse(fs.readFileSync(path.join(SCHEMAS, uri.slice('/schemas/'.length)), 'utf8')); -const ajv = new Ajv({ allErrors: true, strict: false, discriminator: true, loadSchema: async (uri) => read(uri) }); -addFormats(ajv); - -let validateRequest; -let validateForecast; -let validatePackage; -let validateResponse; -let validateCreate; -before(async () => { - // A single Ajv instance shares the PackageRequest refs across these validators. - validateRequest = await ajv.compileAsync(read(REQUEST_URI)); - validateForecast = ajv.getSchema(FORECAST_URI); - validatePackage = ajv.getSchema(PACKAGE_URI); - validateResponse = await ajv.compileAsync(read(RESPONSE_URI)); - validateCreate = ajv.getSchema(CREATE_URI) || await ajv.compileAsync(read(CREATE_URI)); -}); - -const proposedPackage = () => ({ - pricing_option_id: 'cpm_guaranteed', - budget: 25000, - start_time: '2026-11-01T00:00:00Z', - end_time: '2026-11-30T23:59:59Z', - targeting_overlay: { geo_countries: ['US'] }, -}); -const productFixture = () => ({ - product_id: 'prod_homepage_takeover', - name: 'Homepage takeover', - description: 'Guaranteed homepage display inventory.', - publisher_properties: [{ publisher_domain: 'streamhaus.example', selection_type: 'all' }], - format_ids: [{ agent_url: 'https://creatives.adcontextprotocol.org', id: 'display_300x250' }], - delivery_type: 'guaranteed', - pricing_options: [{ pricing_option_id: 'cpm_guaranteed', pricing_model: 'cpm', currency: 'USD', fixed_price: 10 }], - reporting_capabilities: { - available_reporting_frequencies: ['daily'], expected_delay_minutes: 60, timezone: 'UTC', - supports_webhooks: false, available_metrics: ['impressions'], date_range_support: 'date_range', - }, -}); -const request = (entry = {}) => ({ - buying_mode: 'refine', - refine: [{ scope: 'product', product_id: 'prod_homepage_takeover', package: proposedPackage(), ...entry }], -}); -const check = (validate, value, expected = true) => { - assert.equal(validate(value), expected, JSON.stringify(validate.errors, null, 2)); -}; - -test('an exact package is optional and accepts explicit or default include without ask', () => { - check(validateRequest, request()); - check(validateRequest, request({ action: 'include' })); - check(validateRequest, { ...request(), fields: ['name'] }); - check(validateRequest, { buying_mode: 'refine', refine: [{ scope: 'product', product_id: 'prod_homepage_takeover' }] }); - for (const action of ['omit', 'more_like_this']) { - check(validateRequest, { buying_mode: 'refine', refine: [{ scope: 'product', product_id: 'prod_homepage_takeover', action }] }); - } - check(validateRequest, { buying_mode: 'refine', refine: [{ scope: 'proposal', proposal_id: 'prop_launch', action: 'finalize' }] }); - check(validateRequest, { - buying_mode: 'refine', - refine: [ - { scope: 'request', ask: 'Keep the same product selection' }, - ...request().refine, - { scope: 'product', product_id: 'prod_display_ros', action: 'omit' }, - ], - }); -}); - -test('a package cannot be attached to omit, more_like_this, or other scopes', () => { - for (const action of ['omit', 'more_like_this', 'finalize']) { - check(validateRequest, request({ action }), false); - } - check(validateRequest, { - buying_mode: 'refine', - refine: [{ scope: 'request', ask: 'Check availability', package: proposedPackage() }], - }, false); - check(validateRequest, { - buying_mode: 'refine', - refine: [{ scope: 'proposal', proposal_id: 'prop_launch', package: proposedPackage() }], - }, false); - for (const buying_mode of ['brief', 'wholesale']) { - check(validateRequest, { ...request(), buying_mode, ...(buying_mode === 'brief' ? { brief: 'Launch campaign' } : {}) }, false); - } - check(validateRequest, { - buying_mode: 'refine', - refine: [...request().refine, { scope: 'proposal', proposal_id: 'prop_launch', action: 'finalize' }], - }, false); -}); - -test('pricing option and numeric budget are required and product identity is supplied only by the entry', () => { - for (const key of ['pricing_option_id', 'budget']) { - const pkg = proposedPackage(); - delete pkg[key]; - check(validateRequest, request({ package: pkg }), false); - } - for (const budget of [-1, '25000', { amount: 25000, currency: 'USD' }]) { - check(validateRequest, request({ package: { ...proposedPackage(), budget } }), false); - } - check(validateRequest, request({ package: { ...proposedPackage(), product_id: 'prod_other' } }), false); - check(validateRequest, request({ package: null }), false); - check(validateRequest, request({ package: [] }), false); - check(validateRequest, { buying_mode: 'refine', refine: [{ scope: 'product', package: proposedPackage() }] }, false); -}); - -test('flight dates may be inherited and package targeting preserves create inheritance and clear inputs', () => { - const pkg = { pricing_option_id: 'cpm_guaranteed', budget: 25000 }; - check(validateRequest, { - ...request({ package: pkg }), - filters: { start_date: '2026-11-01', end_date: '2026-11-30' }, - }); - check(validateRequest, request({ package: { ...pkg, targeting_overlay: {} } })); - check(validateRequest, request({ package: { ...pkg, impressions: 2500000, targeting_overlay: { geo_countries: null } } })); - for (const update of [ - { start_time: 'asap' }, - { start_time: '2026-11-01' }, - { end_time: 'not-a-date' }, - { impressions: -1 }, - { targeting_overlay: { geo_countries: 'US' } }, - ]) { - check(validateRequest, request({ package: { ...pkg, ...update } }), false); - } -}); - -test('forecast fields and cross-field constraints stay aligned with create packages', () => { - const booking = read(PACKAGE_URI); - const forecast = read(FORECAST_URI); - assert.deepEqual(Object.keys(forecast.properties), Object.keys(booking.properties).filter((key) => key !== 'product_id')); - for (const [key, field] of Object.entries(forecast.properties)) { - assert.equal(field.$ref, `${PACKAGE_URI}#/properties/${key}`); - } - assert.deepEqual(forecast.dependencies, booking.dependencies); - assert.deepEqual(forecast.not, { $ref: `${PACKAGE_URI}#/not` }); - assert.deepEqual(forecast.allOf.slice(0, -1), booking.allOf.map((_, i) => ({ $ref: `${PACKAGE_URI}#/allOf/${i}` }))); - - const cases = [ - [{}, true], - [{ start_requires_all_creatives_approved: false }, true], - [{ start_requires_all_creatives_approved: true }, true], - [{ start_requires_all_creatives_approved: 'true' }, false], - [{ format_kind: 'image', params: { width: 300, height: 250 } }, true], - [{ format_kind: 'image', params: { width: 300 } }, false], - [{ params: { width: 300, height: 250 } }, false], - [{ bidding: { automatic: true } }, true], - [{ bidding: { automatic: true }, bid_price: 10 }, false], - [{ bidding: { automatic: true }, optimization_goals: [ - { kind: 'metric', metric: 'clicks', priority: 1, target: { kind: 'cost_per', value: 1 } }, - ] }, false], - [{ budget_cap_timezone: 'UTC' }, false], - [{ capability_ids: ['unsupported'] }, false], - ]; - for (const [extra, valid] of cases) { - const pkg = { ...proposedPackage(), ...extra }; - check(validateForecast, pkg, valid); - check(validatePackage, { product_id: 'prod_homepage_takeover', ...pkg }, valid); - } -}); - -test('the existing response shape carries exact availability, shortfall, and unsupported-entry outcomes', () => { - const product = productFixture(); - for (const [available, availability_status] of [[3000000, 'available'], [2000000, 'unavailable'], [0, 'unavailable']]) { - const response = { - status: 'completed', - products: [{ - ...product, - forecast: { - forecast_range_unit: 'availability', method: 'modeled', currency: 'USD', - generated_at: '2026-10-24T12:00:00Z', valid_until: '2026-10-24T12:05:00Z', - points: [{ metrics: { impressions: { mid: available } }, availability_status }], - }, - }], - cache_scope: 'public', - refinement_applied: [{ - scope: 'product', product_id: product.product_id, result_product_id: product.product_id, - resolved_start_time: proposedPackage().start_time, resolved_end_time: proposedPackage().end_time, - status: 'applied', - }], - }; - check(validateResponse, response); - } - check(validateResponse, { - status: 'completed', products: [product], cache_scope: 'public', - refinement_applied: [{ scope: 'product', product_id: product.product_id, status: 'unable', notes: 'The ad server cannot forecast this targeting.' }], - }); - // Response validation has no request context: unchanged legacy outcomes remain valid. - check(validateResponse, { status: 'completed', products: [product], cache_scope: 'public' }); -}); - -test('new package inputs carry 3.3 version metadata without re-versioning the legacy task', () => { - assert.equal(read(FORECAST_URI)['x-added-in'], '3.3.0'); - assert.equal(read(REQUEST_URI).properties.refine.items.oneOf[1].properties.package['x-added-in'], '3.3.0'); - assert.equal(read(REQUEST_URI)['x-added-in'], undefined); - const receipt = read(RESPONSE_URI).properties.refinement_applied.items.oneOf[1]; - for (const name of ['result_product_id', 'resolved_start_time', 'resolved_end_time']) { - assert.equal(receipt.properties[name]['x-added-in'], '3.3.0'); - } -}); - -test('resolved timestamps retain booking validation without importing the full package graph', () => { - const fields = read(RESPONSE_URI).properties.refinement_applied.items.oneOf[1].properties; - for (const [receiptName, packageName] of [['resolved_start_time', 'start_time'], ['resolved_end_time', 'end_time']]) { - const { description, 'x-added-in': addedIn, ...constraints } = fields[receiptName]; - const { description: packageDescription, ...packageConstraints } = read(PACKAGE_URI).properties[packageName]; - assert.ok(description && packageDescription); - assert.equal(addedIn, '3.3.0'); - assert.deepEqual(constraints, packageConstraints); - } -}); - -test('reminted products and inherited local flight boundaries round-trip into create without relying on product order', () => { - const input = { - buying_mode: 'refine', adcp_version: '3.3', account: { account_id: 'account_streamhaus' }, - filters: { start_date: '2026-11-01', end_date: '2026-11-30' }, - targeting_overlay: { geo_countries: ['US'] }, - refine: [ - { scope: 'product', product_id: 'prod_homepage_takeover', package: { - pricing_option_id: 'cpm_guaranteed', budget: 25000, targeting_overlay: { geo_countries: null }, - } }, - { scope: 'product', product_id: 'prod_display_ros', package: { - pricing_option_id: 'cpm_guaranteed', budget: 5000, targeting_overlay: { geo_countries: ['CA'] }, - } }, - ], - }; - const start = '2026-11-01T00:00:00-05:00'; - const end = '2026-11-30T23:59:59-05:00'; - const products = input.refine.map((entry, index) => ({ - ...productFixture(), product_id: `${entry.product_id}_configured`, - is_custom: true, expires_at: '2026-10-24T12:05:00Z', overlay_support: { geo_countries: true }, - forecast: { - forecast_range_unit: 'availability', method: 'modeled', currency: 'USD', - points: [{ metrics: { impressions: { mid: index === 0 ? 3000000 : 600000 } }, availability_status: 'available' }], - }, - })); - const response = { - status: 'completed', adcp_version: '3.3', cache_scope: 'account', - products: [...products].reverse(), - refinement_applied: input.refine.map((entry, index) => ({ - scope: 'product', product_id: entry.product_id, result_product_id: products[index].product_id, - resolved_start_time: start, resolved_end_time: end, status: 'applied', - })), - }; - check(validateRequest, input); - check(validateResponse, response); - - const packages = input.refine.map((entry, index) => { - const outcome = response.refinement_applied[index]; - assert.equal(outcome.product_id, entry.product_id); - const matching = response.products.filter((product) => product.product_id === outcome.result_product_id); - assert.equal(matching.length, 1); - const selectedPricing = matching[0].pricing_options.find((option) => option.pricing_option_id === entry.package.pricing_option_id); - assert.deepEqual(selectedPricing, productFixture().pricing_options[0]); - return { - ...entry.package, product_id: outcome.result_product_id, - start_time: outcome.resolved_start_time, end_time: outcome.resolved_end_time, - }; - }); - check(validateCreate, { - idempotency_key: 'forecast-purchase-0001', account: input.account, - brand: { domain: 'nova-motors.example' }, start_time: start, end_time: end, packages, - }); - assert.equal(packages[0].targeting_overlay.geo_countries, null); - assert.equal(packages[0].product_id, response.products[1].product_id); - assert.equal(packages[1].product_id, response.products[0].product_id); - - for (const key of ['result_product_id', 'resolved_start_time', 'resolved_end_time']) { - const incomplete = structuredClone(response); - delete incomplete.refinement_applied[0][key]; - check(validateResponse, incomplete, false); - } - for (const update of [{ result_product_id: '' }, { resolved_start_time: 'not-a-time' }, { status: 'unable' }]) { - const invalid = structuredClone(response); - Object.assign(invalid.refinement_applied[0], update); - check(validateResponse, invalid, false); - } -});