From c0d2ee6d3e69f2d5d883d6b710787f01a76406f5 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 24 Oct 2026 19:29:37 +0000 Subject: [PATCH 1/5] feat(schema): add media_buy.supported_delivery_types to capabilities Sellers declare whether they sell guaranteed inventory, non_guaranteed inventory, or both, mirroring supported_pricing_models, so buyers can filter sellers before calling get_products. Like every capability declaration it is a commitment: a declaring seller returns only products with a listed delivery_type. When absent, buyers treat delivery types as unknown. Split out of #8454, whose x-adcp-applies-when annotation stays on the RFC track (#8452). Background: #8359. Co-Authored-By: Claude Opus 5.5 (1M context) --- .changeset/supported-delivery-types.md | 5 +++++ docs/protocol/capabilities-explorer.mdx | 1 + docs/reference/migration/3-2-to-3-3.mdx | 1 + docs/reference/whats-new-in-3-3.mdx | 1 + .../protocol/get-adcp-capabilities-response.json | 10 ++++++++++ 5 files changed, 18 insertions(+) create mode 100644 .changeset/supported-delivery-types.md diff --git a/.changeset/supported-delivery-types.md b/.changeset/supported-delivery-types.md new file mode 100644 index 00000000000..28194675072 --- /dev/null +++ b/.changeset/supported-delivery-types.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": minor +--- + +Add `media_buy.supported_delivery_types` to `get_adcp_capabilities`. A seller declares whether it sells `guaranteed` inventory, `non_guaranteed` inventory, or both, mirroring `supported_pricing_models`, so buyers can filter sellers before calling `get_products`. Like every capability declaration, it is a commitment: a declaring seller returns only products with a listed `delivery_type`. When absent, buyers treat the seller's delivery types as unknown. diff --git a/docs/protocol/capabilities-explorer.mdx b/docs/protocol/capabilities-explorer.mdx index 71bdd3e11ea..4f2c6f7b4c5 100644 --- a/docs/protocol/capabilities-explorer.mdx +++ b/docs/protocol/capabilities-explorer.mdx @@ -79,6 +79,7 @@ The largest domain. Sub-namespaces are where most media-buying flags belong. - **`portfolio`** — portfolio-management capabilities. - **`reporting_delivery_methods`** — how reporting is delivered. - **`supported_pricing_models`** — array (CPM, CPC, CPCV, CPP, revenue share, flat rate, etc.). +- **`supported_delivery_types`** — array of `guaranteed` and/or `non_guaranteed` (3.3). When declared, every product carries a listed `delivery_type`. [Propose a flag for `media_buy.features`](https://github.com/adcontextprotocol/adcp/issues/new?title=Add+media_buy+feature:+%3Cflag%3E&body=Schema+location:+%60.media_buy.features%60%0A%0A%23%23+Proposal%0A%0A...%0A%0A%23%23+Why+a+feature+flag+and+not+a+new+task%0A%0A...%0A%0A%23%23+Conformance+probe%0A%0AHow+can+a+buyer+verify+this+capability+is+actually+honored?+...&labels=rfc,capabilities) diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index 4f4532aa65b..79625582f90 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -535,6 +535,7 @@ The field is stable in 3.3, not experimental. It completes the basis vocabulary ### Catalogs, signing, and extensions +- **Delivery types.** Declare `media_buy.supported_delivery_types` with the delivery types you sell, and return only products whose `delivery_type` is listed. Buyers treat an absent declaration as unknown, not as an empty set. - **Catalog ingestion.** Declare `media_buy.features.catalog_ingestion` with `accepted_catalog_types`, `ingestion_modes`, and `item_status_reporting` (required), plus `supported_feed_formats` whenever `feed_url` is listed. Declaring it requires `catalog_management: true`. Reject an unlisted catalog type, mode, or feed format, or an explicit `content_id_type` outside a declared list, with `UNSUPPORTED_FEATURE` before mutation, including on `dry_run`; inline items beyond `max_inline_items_per_request` fail with `INVALID_REQUEST`. Buyers treat an absent declaration as unknown, not unrestricted. See [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs#ingestion-compatibility). - **`request_signing.operation_sources`.** List `mcp_tools_call` and `a2a_invocation_skill` only for the sources your verifier implements and passes vectors for, and list every source you support: an array without `a2a_invocation_skill` tells peers you do not enforce over A2A. See [above](#a2a-operation-resolution-hardening-becomes-must). - **`trust.json` (experimental).** `trust/v1/trust.json` and `trust/v1/trust-acknowledgements.json` are published under `identity.trust_json` (#8067). An agent is identified by the canonical origin of its URL, one agent per origin, and the record carries no keys (#8121). In 3.3 its reader is the experimental Web Bot Auth profile, which derives the record from the agent's origin, and grants are read at `sync_accounts`. Publishers declare nothing. See [trust.json](/docs/reference/trust-json) and the [agent identity migration guide](/docs/reference/migration/agent-identity-3-3). diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index d63c962be65..a5ad49ec45f 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -112,6 +112,7 @@ Two more guarantees loosen here, and the response-size default a third ([below]( - **Signal readiness (experimental).** `get_signals` results can carry `signal_status` (`processing`, `ready`, `failed`) and the `source_audience_id` a custom segment was built from. Feature id `signals.signal_lifecycle`. See [Custom segments built from a seed audience](/docs/signals/tasks/get_signals#custom-segments-built-from-a-seed-audience). - **Event source archive.** A seller that declares `media_buy.event_source_archive` accepts `archived` on `sync_event_sources` items to archive or restore a source without losing its configuration. See [Archiving an event source](/docs/media-buy/task-reference/sync_event_sources#archiving-an-event-source). - **Creative and brand.** `list_creatives` echoes creative-level `provenance`; brand.json gains a brand-wide `prohibited_terms` list; rights constraints can carry advisory `channels[]` and `excluded_channels[]` (experimental, `brand.rights_lifecycle`); and the HTML-markup legacy formats project to `display_tag` inline markup instead of `html5`. +- **Delivery types.** `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` inventory, `non_guaranteed` inventory, or both, so buyers can skip sellers that don't sell what they're buying before calling `get_products`. A declaring seller returns only products with a listed `delivery_type`. - **The `ext.adcp` namespace.** `ext.adcp` is a registered, AdCP-owned extension namespace. Its first member is an optional `opportunity` binding for cooperating 3.2 `get_products` integrations. See [AdCP opportunity extension](/docs/building/by-layer/L2/context-sessions#adcp-opportunity-extension). ## Bounded agent responses diff --git a/static/schemas/source/protocol/get-adcp-capabilities-response.json b/static/schemas/source/protocol/get-adcp-capabilities-response.json index 2e7b873073c..4963f249d3e 100644 --- a/static/schemas/source/protocol/get-adcp-capabilities-response.json +++ b/static/schemas/source/protocol/get-adcp-capabilities-response.json @@ -1555,6 +1555,16 @@ "minItems": 1, "uniqueItems": true }, + "supported_delivery_types": { + "x-added-in": "3.3.0", + "type": "array", + "description": "Delivery types this seller sells across its product portfolio: guaranteed (reserved inventory) and/or non_guaranteed. Buyers can use this for pre-flight filtering before querying individual products. Like every capability declaration, it is a commitment: the products this seller returns carry a delivery_type listed here. When absent, the seller has not declared its delivery types, and buyers treat them as unknown rather than as an empty set.", + "items": { + "$ref": "/schemas/enums/delivery-type.json" + }, + "minItems": 1, + "uniqueItems": true + }, "buying_modes": { "type": "array", "description": "Buying modes this seller supports on get_products. 'brief' (semantic discovery driven by the brief) is universally supported and implicit. 'wholesale' (raw wholesale product feed enumeration — caller omits brief and the seller returns the full priced product feed, paginated) is opt-in and SHOULD be declared explicitly so buyers can probe before issuing wholesale calls. 'refine' lets buyers iterate on prior products/proposals and is also the vehicle for finalizing draft proposals when the seller returns them. Sellers MAY declare ['brief', 'wholesale'] to signal wholesale support; absent declaration is treated as ['brief'] for wholesale-feed probing purposes and sellers MAY return INVALID_REQUEST for wholesale calls they do not support. Symmetric with signals.discovery_modes.", From be79daaf12e7485e6d23daf40306d26a802878d1 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 24 Oct 2026 22:14:12 +0000 Subject: [PATCH 2/5] fix(schema): distinguish supported_delivery_types from the display_tag parameter Review on #8458 found that display_tag's format parameter is also named supported_delivery_types (creative serving modes such as inline_markup). The description now names the product delivery_type enum and says the two are unrelated. Co-Authored-By: Claude Opus 5.5 (1M context) --- .../schemas/source/protocol/get-adcp-capabilities-response.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/static/schemas/source/protocol/get-adcp-capabilities-response.json b/static/schemas/source/protocol/get-adcp-capabilities-response.json index 4963f249d3e..eaf53378159 100644 --- a/static/schemas/source/protocol/get-adcp-capabilities-response.json +++ b/static/schemas/source/protocol/get-adcp-capabilities-response.json @@ -1558,7 +1558,7 @@ "supported_delivery_types": { "x-added-in": "3.3.0", "type": "array", - "description": "Delivery types this seller sells across its product portfolio: guaranteed (reserved inventory) and/or non_guaranteed. Buyers can use this for pre-flight filtering before querying individual products. Like every capability declaration, it is a commitment: the products this seller returns carry a delivery_type listed here. When absent, the seller has not declared its delivery types, and buyers treat them as unknown rather than as an empty set.", + "description": "Delivery types this seller sells across its product portfolio: guaranteed (reserved inventory) and/or non_guaranteed. Buyers can use this for pre-flight filtering before querying individual products. Like every capability declaration, it is a commitment: the products this seller returns carry a delivery_type listed here. When absent, the seller has not declared its delivery types, and buyers treat them as unknown rather than as an empty set. Values come from the product delivery_type enum (guaranteed, non_guaranteed); this is unrelated to the display_tag format parameter of the same name, which lists creative serving modes such as inline_markup.", "items": { "$ref": "/schemas/enums/delivery-type.json" }, From e96b45ff44934006f7a69b75148976bcdf3fe96c Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 24 Oct 2026 19:33:32 +0000 Subject: [PATCH 3/5] feat(schema): key optional fields to capabilities with x-adcp-applies-when Adds the x-adcp-applies-when annotation. It names the capability declarations (delivery_types, pricing_models, capabilities paths) that make an optional property relevant, and never changes validation. Projections, such as a non-guaranteed-only MCP tool surface, use it to drop optional fields from one canonical schema, with no seller-specific SDKs. Initial annotations: product.cancellation_policy (guaranteed); floor_price and price_guidance on pricing options (non_guaranteed); the product's conversion-tracking, vendor-metric-optimization, and Trusted Match fields (their capability blocks). scripts/lint-applies-when.cjs checks every annotation. Builds on #8458 (supported_delivery_types). Refs #8452. Co-Authored-By: Claude Opus 5.5 (1M context) --- .changeset/x-adcp-applies-when.md | 5 + .github/workflows/build-check.yml | 3 + docs/protocol/capabilities-explorer.mdx | 2 +- docs/reference/migration/3-2-to-3-3.mdx | 2 +- docs/reference/schema-extensions.mdx | 54 ++++ docs/reference/whats-new-in-3-3.mdx | 2 +- package.json | 1 + scripts/lint-applies-when.cjs | 243 ++++++++++++++++++ .../source/core/canonical-pricing-option.json | 4 +- static/schemas/source/core/product.json | 5 + .../source/pricing-options/cpc-option.json | 2 + .../source/pricing-options/cpcv-option.json | 2 + .../source/pricing-options/cpm-option.json | 2 + .../source/pricing-options/cpp-option.json | 2 + .../source/pricing-options/cpv-option.json | 2 + .../pricing-options/flat-rate-option.json | 2 + .../source/pricing-options/time-option.json | 2 + .../source/pricing-options/vcpm-option.json | 2 + tests/lint-applies-when.test.cjs | 169 ++++++++++++ 19 files changed, 501 insertions(+), 5 deletions(-) create mode 100644 .changeset/x-adcp-applies-when.md create mode 100644 scripts/lint-applies-when.cjs create mode 100644 tests/lint-applies-when.test.cjs diff --git a/.changeset/x-adcp-applies-when.md b/.changeset/x-adcp-applies-when.md new file mode 100644 index 00000000000..2f19b3a5bf5 --- /dev/null +++ b/.changeset/x-adcp-applies-when.md @@ -0,0 +1,5 @@ +--- +"adcontextprotocol": minor +--- + +Add the `x-adcp-applies-when` schema annotation (#8452). It names the capability declarations (`delivery_types`, `pricing_models`, `capabilities` paths) that make a property relevant, and never changes validation. Projections, such as a non-guaranteed-only MCP tool surface, use it to drop optional fields from one canonical schema. Initial annotations cover `product.cancellation_policy` (guaranteed), `floor_price` and `price_guidance` on pricing options (non_guaranteed), and the product's conversion-tracking, vendor-metric-optimization, and Trusted Match fields (their capability blocks). `scripts/lint-applies-when.cjs` checks every annotation. diff --git a/.github/workflows/build-check.yml b/.github/workflows/build-check.yml index c223d62c78d..dad6f86f803 100644 --- a/.github/workflows/build-check.yml +++ b/.github/workflows/build-check.yml @@ -74,6 +74,9 @@ jobs: - name: Language-tag schema reference guard run: npm run test:language-tag-refs + - name: x-adcp-applies-when annotation guard + run: npm run test:applies-when + - name: Fetch 3.0.x for error-code drift comparison if: github.ref != 'refs/heads/3.0.x' && github.base_ref != '3.0.x' run: git fetch --depth=1 origin +3.0.x:refs/remotes/origin/3.0.x diff --git a/docs/protocol/capabilities-explorer.mdx b/docs/protocol/capabilities-explorer.mdx index 4f2c6f7b4c5..4ba234775bc 100644 --- a/docs/protocol/capabilities-explorer.mdx +++ b/docs/protocol/capabilities-explorer.mdx @@ -79,7 +79,7 @@ The largest domain. Sub-namespaces are where most media-buying flags belong. - **`portfolio`** — portfolio-management capabilities. - **`reporting_delivery_methods`** — how reporting is delivered. - **`supported_pricing_models`** — array (CPM, CPC, CPCV, CPP, revenue share, flat rate, etc.). -- **`supported_delivery_types`** — array of `guaranteed` and/or `non_guaranteed` (3.3). When declared, every product carries a listed `delivery_type`. +- **`supported_delivery_types`** — array of `guaranteed` and/or `non_guaranteed` (3.3). When declared, every product carries a listed `delivery_type`. Schema fields annotated with [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when) `delivery_types` resolve against it. [Propose a flag for `media_buy.features`](https://github.com/adcontextprotocol/adcp/issues/new?title=Add+media_buy+feature:+%3Cflag%3E&body=Schema+location:+%60.media_buy.features%60%0A%0A%23%23+Proposal%0A%0A...%0A%0A%23%23+Why+a+feature+flag+and+not+a+new+task%0A%0A...%0A%0A%23%23+Conformance+probe%0A%0AHow+can+a+buyer+verify+this+capability+is+actually+honored?+...&labels=rfc,capabilities) diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index 79625582f90..3ad2210be4b 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -535,7 +535,7 @@ The field is stable in 3.3, not experimental. It completes the basis vocabulary ### Catalogs, signing, and extensions -- **Delivery types.** Declare `media_buy.supported_delivery_types` with the delivery types you sell, and return only products whose `delivery_type` is listed. Buyers treat an absent declaration as unknown, not as an empty set. +- **Delivery types.** Declare `media_buy.supported_delivery_types` with the delivery types you sell, and return only products whose `delivery_type` is listed. Buyers treat an absent declaration as unknown, not as an empty set. Projections, such as a non-guaranteed-only MCP tool surface, resolve the `x-adcp-applies-when` schema annotation against this field and the other capability blocks; the annotation never changes validation. See [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when). - **Catalog ingestion.** Declare `media_buy.features.catalog_ingestion` with `accepted_catalog_types`, `ingestion_modes`, and `item_status_reporting` (required), plus `supported_feed_formats` whenever `feed_url` is listed. Declaring it requires `catalog_management: true`. Reject an unlisted catalog type, mode, or feed format, or an explicit `content_id_type` outside a declared list, with `UNSUPPORTED_FEATURE` before mutation, including on `dry_run`; inline items beyond `max_inline_items_per_request` fail with `INVALID_REQUEST`. Buyers treat an absent declaration as unknown, not unrestricted. See [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs#ingestion-compatibility). - **`request_signing.operation_sources`.** List `mcp_tools_call` and `a2a_invocation_skill` only for the sources your verifier implements and passes vectors for, and list every source you support: an array without `a2a_invocation_skill` tells peers you do not enforce over A2A. See [above](#a2a-operation-resolution-hardening-becomes-must). - **`trust.json` (experimental).** `trust/v1/trust.json` and `trust/v1/trust-acknowledgements.json` are published under `identity.trust_json` (#8067). An agent is identified by the canonical origin of its URL, one agent per origin, and the record carries no keys (#8121). In 3.3 its reader is the experimental Web Bot Auth profile, which derives the record from the agent's origin, and grants are read at `sync_accounts`. Publishers declare nothing. See [trust.json](/docs/reference/trust-json) and the [agent identity migration guide](/docs/reference/migration/agent-identity-3-3). diff --git a/docs/reference/schema-extensions.mdx b/docs/reference/schema-extensions.mdx index ab18cef659f..b018e5bdc56 100644 --- a/docs/reference/schema-extensions.mdx +++ b/docs/reference/schema-extensions.mdx @@ -157,6 +157,60 @@ Adding `x-adcp-hoist` to a previously-inlined source schema is wire-compatible ( - Introduced in [#4557](https://github.com/adcontextprotocol/adcp/issues/4557). Successor to [#3145](https://github.com/adcontextprotocol/adcp/issues/3145) phase 2. +## `x-adcp-applies-when` + +Names the seller capability declarations that make a property relevant. The annotation is documentary and non-validating: the property's JSON Schema still controls wire validation, and validators MUST ignore the keyword. + +It exists so a seller can expose a narrower surface without a seller-specific schema or SDK. For example, a seller that sells only non-guaranteed inventory can drop guaranteed-only fields from its MCP tool schemas. Such a narrowed schema is a **projection**: a pure function of one canonical schema and the seller's own [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) response. Docs and storyboard coverage checks read the same annotation. + +```jsonc +"cancellation_policy": { + "x-adcp-applies-when": { "delivery_types": ["guaranteed"] }, + "$ref": "/schemas/core/cancellation-policy.json" +} +``` + +### Keys + +The value is an object with one or more of these keys. Each key holds a non-empty array. + +| Key | Values | Matched against | +|---|---|---| +| `delivery_types` | [`delivery-type`](https://adcontextprotocol.org/schemas/v3/enums/delivery-type.json) values | `media_buy.supported_delivery_types` | +| `pricing_models` | [`pricing-model`](https://adcontextprotocol.org/schemas/v3/enums/pricing-model.json) values | `media_buy.supported_pricing_models` | +| `capabilities` | Dotted paths into the `get_adcp_capabilities` response, such as `media_buy.conversion_tracking` | Satisfied when the path is present and not `false` | + +There is no `channels` key yet. `portfolio.primary_channels` is a brief-routing scope, not an exhaustive declaration of the channels a seller sells. + +### Semantics + +- **Any match counts.** The property is relevant when any listed value matches the seller's declaration. A projection that can't express both conditions together, such as "guaranteed and proposals", keeps more fields than it needs, never fewer. +- **Fail open.** When the seller hasn't declared the matched capability, for example it omits `supported_delivery_types`, the property stays relevant. +- **Projections only remove.** A projection MAY drop optional properties whose annotation doesn't match. It MUST NOT rename, retype, or add required properties. A payload valid against a projection is valid against the canonical schema. +- **Never on required properties.** A property that carries the annotation MUST NOT be listed in its parent's `required`. +- **Union arms need no annotation.** Arms of a discriminated union, such as the pricing options keyed by `pricing_model`, are already selected by their discriminator. + +### Conformance + +- Validators MUST ignore `x-adcp-applies-when`. Projection is optional: a seller that exposes the full canonical surface is conformant. +- `scripts/lint-applies-when.cjs` checks every annotation: only known keys, non-empty arrays, values valid against their enums, every capability path resolving in `get-adcp-capabilities-response.json`, and no annotated property listed as required. + +### Current usage + +| Property | Annotation | +|---|---| +| `product.cancellation_policy` | `delivery_types: ["guaranteed"]` | +| `floor_price`, `price_guidance` on each pricing option that has them, and on `canonical-pricing-option` | `delivery_types: ["non_guaranteed"]` | +| `product.conversion_tracking`, `product.measurement_readiness` | `capabilities: ["media_buy.conversion_tracking"]` | +| `product.vendor_metric_optimization` | `capabilities: ["media_buy.vendor_metric_optimization"]` | +| `product.trusted_match` | `capabilities: ["media_buy.execution.trusted_match"]` | + +`fixed_price` is deliberately not annotated: non-guaranteed broadcast scatter and PMP deals are fixed-price too. + +### History + +- Introduced in 3.3 by [#8452](https://github.com/adcontextprotocol/adcp/issues/8452), from the [#8359](https://github.com/adcontextprotocol/adcp/issues/8359) discussion. + ## Future extensions New `x-adcp-*` keywords are added in minor releases. Consumers MUST tolerate unknown `x-` keywords without erroring. The convention reserves the `x-adcp-` namespace; vendor-specific or deployment-specific annotations SHOULD use a vendor-specific prefix (e.g., `x-yourorg-`) to avoid collision. diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index a5ad49ec45f..410728f2705 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -112,7 +112,7 @@ Two more guarantees loosen here, and the response-size default a third ([below]( - **Signal readiness (experimental).** `get_signals` results can carry `signal_status` (`processing`, `ready`, `failed`) and the `source_audience_id` a custom segment was built from. Feature id `signals.signal_lifecycle`. See [Custom segments built from a seed audience](/docs/signals/tasks/get_signals#custom-segments-built-from-a-seed-audience). - **Event source archive.** A seller that declares `media_buy.event_source_archive` accepts `archived` on `sync_event_sources` items to archive or restore a source without losing its configuration. See [Archiving an event source](/docs/media-buy/task-reference/sync_event_sources#archiving-an-event-source). - **Creative and brand.** `list_creatives` echoes creative-level `provenance`; brand.json gains a brand-wide `prohibited_terms` list; rights constraints can carry advisory `channels[]` and `excluded_channels[]` (experimental, `brand.rights_lifecycle`); and the HTML-markup legacy formats project to `display_tag` inline markup instead of `html5`. -- **Delivery types.** `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` inventory, `non_guaranteed` inventory, or both, so buyers can skip sellers that don't sell what they're buying before calling `get_products`. A declaring seller returns only products with a listed `delivery_type`. +- **Delivery types.** `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` inventory, `non_guaranteed` inventory, or both, so buyers can skip sellers that don't sell what they're buying before calling `get_products`. A declaring seller returns only products with a listed `delivery_type`. The `x-adcp-applies-when` schema annotation names the capability that makes a field relevant, for example `floor_price` for `non_guaranteed` and `cancellation_policy` for `guaranteed`, so a seller can expose a narrower tool surface derived from one canonical schema. The annotation never changes validation. See [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when). - **The `ext.adcp` namespace.** `ext.adcp` is a registered, AdCP-owned extension namespace. Its first member is an optional `opportunity` binding for cooperating 3.2 `get_products` integrations. See [AdCP opportunity extension](/docs/building/by-layer/L2/context-sessions#adcp-opportunity-extension). ## Bounded agent responses diff --git a/package.json b/package.json index f88cb096ba6..b43fb9b4939 100644 --- a/package.json +++ b/package.json @@ -147,6 +147,7 @@ "test:test-coverage": "node --test --test-force-exit tests/test-coverage-registration.test.cjs", "test:error-code-drift": "node scripts/lint-error-code-drift.cjs", "test:language-tag-refs": "node --test --test-force-exit --test-timeout=30000 tests/lint-language-tag-refs.test.cjs && node scripts/lint-language-tag-refs.cjs", + "test:applies-when": "node --test --test-force-exit --test-timeout=30000 tests/lint-applies-when.test.cjs && node scripts/lint-applies-when.cjs", "test:compliance-snippets": "node --test --test-force-exit --test-timeout=30000 tests/generate-compliance-snippets.node.mjs tests/link-compliance-symbols.node.mjs && npm run build:compliance -- --check", "test:doc-compliance-drift": "node --test --test-force-exit --test-timeout=30000 tests/lint-doc-compliance-drift.test.cjs tests/lint-conformance-doc-freshness.test.cjs && npm run test:release-instrumentation", "test:release-instrumentation": "node --test --test-force-exit --test-timeout=30000 tests/release-instrumentation.test.cjs", diff --git a/scripts/lint-applies-when.cjs b/scripts/lint-applies-when.cjs new file mode 100644 index 00000000000..0482b664d76 --- /dev/null +++ b/scripts/lint-applies-when.cjs @@ -0,0 +1,243 @@ +#!/usr/bin/env node +/** + * Guard for the `x-adcp-applies-when` schema annotation. + * + * The annotation names the get_adcp_capabilities declarations that make a + * property relevant, so projections (for example a non-guaranteed-only MCP + * tool surface) can drop fields a seller never uses. It never changes wire + * validation, which makes typos silent: a misspelled capability path or enum + * value would just leave a field unprojected. This lint makes them loud. + * + * Rules (docs/reference/schema-extensions.mdx#x-adcp-applies-when): + * - the annotation sits on a property declaration (a member of `properties`); + * - its value is an object using only the known keys, each a non-empty array + * of unique strings; + * - delivery_types / pricing_models values are members of their enums; + * - every capabilities path resolves to a property declared in + * protocol/get-adcp-capabilities-response.json (following $ref); + * - an annotated property is not listed in its parent's `required`, because + * a projection may only remove optional properties. + */ + +'use strict'; + +const path = require('node:path'); + +const { + loadSchemaRegistry, + resolveRef, +} = require('./lint-language-tag-refs.cjs'); + +const REPO_ROOT = path.resolve(__dirname, '..'); +const DEFAULT_SCHEMAS_DIR = path.join(REPO_ROOT, 'static', 'schemas', 'source'); +const ANNOTATION = 'x-adcp-applies-when'; +const CAPABILITIES_RESPONSE = 'protocol/get-adcp-capabilities-response.json'; +const ENUM_KEYS = { + delivery_types: 'enums/delivery-type.json', + pricing_models: 'enums/pricing-model.json', +}; +const KNOWN_KEYS = new Set([...Object.keys(ENUM_KEYS), 'capabilities']); +// Values under these keywords are instance data, not schema declarations. +const NON_SCHEMA_KEYS = new Set(['const', 'default', 'enum', 'examples']); + +function isObject(value) { + return value !== null && typeof value === 'object' && !Array.isArray(value); +} + +function escapePointerToken(value) { + return value.replace(/~/g, '~0').replace(/\//g, '~1'); +} + +function loadEnum(registry, relativePath, errors) { + const document = registry.byKey.get(relativePath); + if (!document || !Array.isArray(document.schema.enum)) { + errors.push(`missing enum schema: ${relativePath}`); + return new Set(); + } + return new Set(document.schema.enum); +} + +/** Unconditional `required` names: the parent's own plus allOf arms without `if`. */ +function requiredNames(parent) { + const names = new Set(Array.isArray(parent.required) ? parent.required : []); + if (Array.isArray(parent.allOf)) { + for (const arm of parent.allOf) { + if (isObject(arm) && !('if' in arm) && Array.isArray(arm.required)) { + arm.required.forEach((name) => names.add(name)); + } + } + } + return names; +} + +/** + * Returns the schemas a property name can resolve to inside `schema`, looking + * through $ref and allOf/anyOf/oneOf arms. + */ +function findPropertySchemas(schema, document, registry, name, seen = new Set()) { + if (!isObject(schema)) return []; + if (typeof schema.$ref === 'string') { + const marker = `${document.relativePath}:${schema.$ref}`; + if (seen.has(marker)) return []; + seen.add(marker); + const resolved = resolveRef(schema.$ref, document, registry); + if (!resolved) return []; + return findPropertySchemas(resolved.node, resolved.document, registry, name, seen); + } + const found = []; + if (isObject(schema.properties) && isObject(schema.properties[name])) { + found.push({ schema: schema.properties[name], document }); + } + for (const keyword of ['allOf', 'anyOf', 'oneOf']) { + if (!Array.isArray(schema[keyword])) continue; + for (const arm of schema[keyword]) { + found.push(...findPropertySchemas(arm, document, registry, name, seen)); + } + } + return found; +} + +function capabilityPathResolves(capabilityPath, registry) { + const root = registry.byKey.get(CAPABILITIES_RESPONSE); + if (!root) return false; + let frontier = [{ schema: root.schema, document: root }]; + for (const segment of capabilityPath.split('.')) { + const next = []; + for (const entry of frontier) { + next.push(...findPropertySchemas(entry.schema, entry.document, registry, segment)); + } + if (next.length === 0) return false; + frontier = next; + } + return true; +} + +function validateValue(value, location, enums, registry) { + const errors = []; + if (!isObject(value)) { + return [`${location}: ${ANNOTATION} must be an object`]; + } + const keys = Object.keys(value); + if (keys.length === 0) errors.push(`${location}: ${ANNOTATION} must name at least one key`); + for (const key of keys) { + if (!KNOWN_KEYS.has(key)) { + errors.push(`${location}: unknown key "${key}" (allowed: ${[...KNOWN_KEYS].join(', ')})`); + continue; + } + const list = value[key]; + if (!Array.isArray(list) || list.length === 0) { + errors.push(`${location}: ${key} must be a non-empty array`); + continue; + } + if (new Set(list).size !== list.length) { + errors.push(`${location}: ${key} has duplicate values`); + } + for (const item of list) { + if (typeof item !== 'string' || item.length === 0) { + errors.push(`${location}: ${key} values must be non-empty strings`); + } else if (key in ENUM_KEYS && !enums[key].has(item)) { + errors.push(`${location}: ${key} value "${item}" is not in ${ENUM_KEYS[key]}`); + } else if (key === 'capabilities' && !capabilityPathResolves(item, registry)) { + errors.push(`${location}: capability path "${item}" does not resolve in ${CAPABILITIES_RESPONSE}`); + } + } + } + return errors; +} + +function collectAnnotations(registry) { + const annotations = []; + const misplaced = []; + + function visit(node, document, pointer, isPropertyDeclaration) { + if (Array.isArray(node)) { + node.forEach((child, index) => visit(child, document, `${pointer}/${index}`, false)); + return; + } + if (!isObject(node)) return; + if (ANNOTATION in node && !isPropertyDeclaration) { + misplaced.push(`${document.relativePath}#${pointer}`); + } + for (const [key, child] of Object.entries(node)) { + if (key === ANNOTATION || NON_SCHEMA_KEYS.has(key)) continue; + const childPointer = `${pointer}/${escapePointerToken(key)}`; + if (key === 'properties' && isObject(child)) { + const required = requiredNames(node); + for (const [name, propertySchema] of Object.entries(child)) { + const propertyPointer = `${childPointer}/${escapePointerToken(name)}`; + if (isObject(propertySchema) && ANNOTATION in propertySchema) { + annotations.push({ + document, + name, + pointer: propertyPointer, + value: propertySchema[ANNOTATION], + required: required.has(name), + }); + } + visit(propertySchema, document, propertyPointer, true); + } + continue; + } + visit(child, document, childPointer, false); + } + } + + for (const document of registry.documents) { + visit(document.schema, document, '', false); + } + return { annotations, misplaced }; +} + +function lintAppliesWhen({ schemasDir = DEFAULT_SCHEMAS_DIR } = {}) { + const registry = loadSchemaRegistry(schemasDir); + const errors = registry.parseErrors.map((error) => `schema parse error: ${error}`); + const enums = {}; + for (const [key, relativePath] of Object.entries(ENUM_KEYS)) { + enums[key] = loadEnum(registry, relativePath, errors); + } + if (!registry.byKey.get(CAPABILITIES_RESPONSE)) { + errors.push(`missing capabilities schema: ${CAPABILITIES_RESPONSE}`); + } + + const { annotations, misplaced } = collectAnnotations(registry); + for (const location of misplaced) { + errors.push(`${location}: ${ANNOTATION} must sit on a property declaration`); + } + for (const annotation of annotations) { + const location = `${annotation.document.relativePath}#${annotation.pointer}`; + errors.push(...validateValue(annotation.value, location, enums, registry)); + if (annotation.required) { + errors.push(`${location}: annotated property "${annotation.name}" is required by its parent; projections may only remove optional properties`); + } + } + + return { ok: errors.length === 0, errors, annotations }; +} + +function readArg(args, name, fallback) { + const index = args.indexOf(name); + return index !== -1 && index + 1 < args.length ? args[index + 1] : fallback; +} + +function main() { + const args = process.argv.slice(2); + const schemasDir = path.resolve(readArg(args, '--schemas', DEFAULT_SCHEMAS_DIR)); + const result = lintAppliesWhen({ schemasDir }); + if (result.ok) { + console.log(`✓ ${ANNOTATION} lint: ${result.annotations.length} annotated properties`); + return; + } + console.error(`✗ ${ANNOTATION} lint failed with ${result.errors.length} error(s):\n`); + result.errors.forEach((error) => console.error(` - ${error}`)); + process.exitCode = 1; +} + +module.exports = { + ANNOTATION, + KNOWN_KEYS, + capabilityPathResolves, + collectAnnotations, + lintAppliesWhen, +}; + +if (require.main === module) main(); diff --git a/static/schemas/source/core/canonical-pricing-option.json b/static/schemas/source/core/canonical-pricing-option.json index 951c9e2f2d0..09b7ed130d2 100644 --- a/static/schemas/source/core/canonical-pricing-option.json +++ b/static/schemas/source/core/canonical-pricing-option.json @@ -12,8 +12,8 @@ }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fixed_price": { "type": "number", "minimum": 0 }, - "floor_price": { "type": "number", "minimum": 0 }, - "price_guidance": { "$ref": "/schemas/pricing-options/price-guidance.json" }, + "floor_price": { "type": "number", "minimum": 0, "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] } }, + "price_guidance": { "$ref": "/schemas/pricing-options/price-guidance.json", "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] } }, "min_spend_per_package": { "type": "number", "minimum": 0 }, "price_breakdown": { "$ref": "/schemas/pricing-options/price-breakdown.json" }, "eligible_adjustments": { diff --git a/static/schemas/source/core/product.json b/static/schemas/source/core/product.json index a64213afc35..b050ef65c8a 100644 --- a/static/schemas/source/core/product.json +++ b/static/schemas/source/core/product.json @@ -168,6 +168,7 @@ "minItems": 1 }, "cancellation_policy": { + "x-adcp-applies-when": { "delivery_types": ["guaranteed"] }, "$ref": "/schemas/core/cancellation-policy.json", "description": "Cancellation terms for this product. Declares the minimum notice period required before cancellation takes effect and any penalties for insufficient notice. Relevant for guaranteed delivery products. Buyers accept these terms by creating a media buy against the product." }, @@ -359,6 +360,7 @@ "additionalProperties": true }, "vendor_metric_optimization": { + "x-adcp-applies-when": { "capabilities": ["media_buy.vendor_metric_optimization"] }, "$ref": "/schemas/core/vendor-metric-optimization.json", "description": "Vendor-attested metric optimization capabilities for this product. Presence indicates the product supports `optimization_goals` with `kind: 'vendor_metric'` — the seller's bidding stack can steer delivery toward a specific vendor's measurement (e.g., DV/IAS/Adelaide attention, Scope3 emissions, Kantar brand lift, retail-media partner metrics). Distinct from `metric_optimization` (seller-native metrics with no vendor binding) and from `reporting_capabilities.vendor_metrics` (which declares what the product can *report* rather than what it can *optimize against*). A product may report a vendor metric without being able to optimize for it. Buyers MUST verify the goal's `(vendor, metric_id)` is in `supported_metrics` AND that the package's `committed_metrics[]` includes a matching `{ scope: 'vendor', vendor, metric_id }` entry — optimization without committed reporting is unverifiable and is rejected at the wire level." }, @@ -368,10 +370,12 @@ "description": "Maximum number of optimization_goals this product accepts on a package. When absent, no limit is declared. Most social platforms accept only 1 goal — buyers sending arrays longer than this value should expect the seller to use only the highest-priority (lowest priority number) goal." }, "measurement_readiness": { + "x-adcp-applies-when": { "capabilities": ["media_buy.conversion_tracking"] }, "$ref": "/schemas/core/measurement-readiness.json", "description": "Assessment of whether the buyer's event source setup is sufficient for this product to optimize effectively. Only present when the seller can evaluate the buyer's account context. Buyers should check this before creating media buys with event-based optimization goals." }, "conversion_tracking": { + "x-adcp-applies-when": { "capabilities": ["media_buy.conversion_tracking"] }, "type": "object", "description": "Conversion event tracking for this product. Presence indicates the product supports optimization_goals with kind: 'event'. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in get_adcp_capabilities.", "properties": { @@ -565,6 +569,7 @@ "$ref": "/schemas/core/acceptance-policy-profile-ids.json" }, "trusted_match": { + "x-adcp-applies-when": { "capabilities": ["media_buy.execution.trusted_match"] }, "type": "object", "description": "Trusted Match Protocol capabilities for this product. When present, the product supports real-time contextual and/or identity matching via TMP. Buyers use this to determine what response types the publisher can accept and whether brands can be selected dynamically at match time.", "properties": { diff --git a/static/schemas/source/pricing-options/cpc-option.json b/static/schemas/source/pricing-options/cpc-option.json index cb524f6271d..6a8f4442122 100644 --- a/static/schemas/source/pricing-options/cpc-option.json +++ b/static/schemas/source/pricing-options/cpc-option.json @@ -26,6 +26,7 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 @@ -37,6 +38,7 @@ "default": false }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/cpcv-option.json b/static/schemas/source/pricing-options/cpcv-option.json index a91958a62e2..409589e437b 100644 --- a/static/schemas/source/pricing-options/cpcv-option.json +++ b/static/schemas/source/pricing-options/cpcv-option.json @@ -26,6 +26,7 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 @@ -37,6 +38,7 @@ "default": false }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/cpm-option.json b/static/schemas/source/pricing-options/cpm-option.json index 1e34ccf2508..7b5aeaf99c7 100644 --- a/static/schemas/source/pricing-options/cpm-option.json +++ b/static/schemas/source/pricing-options/cpm-option.json @@ -26,6 +26,7 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 @@ -37,6 +38,7 @@ "default": false }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/cpp-option.json b/static/schemas/source/pricing-options/cpp-option.json index c73cd1422f0..8c65c8e0d9f 100644 --- a/static/schemas/source/pricing-options/cpp-option.json +++ b/static/schemas/source/pricing-options/cpp-option.json @@ -26,11 +26,13 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/cpv-option.json b/static/schemas/source/pricing-options/cpv-option.json index 7a09fe80a3b..b65584e7bc8 100644 --- a/static/schemas/source/pricing-options/cpv-option.json +++ b/static/schemas/source/pricing-options/cpv-option.json @@ -26,6 +26,7 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 @@ -37,6 +38,7 @@ "default": false }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/flat-rate-option.json b/static/schemas/source/pricing-options/flat-rate-option.json index 01f761d166d..34ff033ae80 100644 --- a/static/schemas/source/pricing-options/flat-rate-option.json +++ b/static/schemas/source/pricing-options/flat-rate-option.json @@ -26,11 +26,13 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/time-option.json b/static/schemas/source/pricing-options/time-option.json index 8fe57e20adf..32099eabf29 100644 --- a/static/schemas/source/pricing-options/time-option.json +++ b/static/schemas/source/pricing-options/time-option.json @@ -26,11 +26,13 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid per time unit for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/static/schemas/source/pricing-options/vcpm-option.json b/static/schemas/source/pricing-options/vcpm-option.json index ee93ebba4f0..4f7e004d722 100644 --- a/static/schemas/source/pricing-options/vcpm-option.json +++ b/static/schemas/source/pricing-options/vcpm-option.json @@ -26,6 +26,7 @@ "minimum": 0 }, "floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "type": "number", "description": "Minimum acceptable bid for auction pricing (mutually exclusive with fixed_price). Bids below this value will be rejected.", "minimum": 0 @@ -37,6 +38,7 @@ "default": false }, "price_guidance": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, "description": "Optional pricing guidance for auction-based bidding", "$ref": "/schemas/pricing-options/price-guidance.json" }, diff --git a/tests/lint-applies-when.test.cjs b/tests/lint-applies-when.test.cjs new file mode 100644 index 00000000000..3348131074a --- /dev/null +++ b/tests/lint-applies-when.test.cjs @@ -0,0 +1,169 @@ +#!/usr/bin/env node + +'use strict'; + +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const test = require('node:test'); + +const { lintAppliesWhen } = require('../scripts/lint-applies-when.cjs'); + +function writeJson(root, relativePath, value) { + const file = path.join(root, relativePath); + fs.mkdirSync(path.dirname(file), { recursive: true }); + fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`); +} + +const BASE_FILES = { + 'enums/delivery-type.json': { + $id: '/schemas/enums/delivery-type.json', + type: 'string', + enum: ['guaranteed', 'non_guaranteed'], + }, + 'enums/pricing-model.json': { + $id: '/schemas/enums/pricing-model.json', + type: 'string', + enum: ['cpm', 'cpp'], + }, + 'core/execution.json': { + $id: '/schemas/core/execution.json', + type: 'object', + properties: { trusted_match: { type: 'object' } }, + }, + 'protocol/get-adcp-capabilities-response.json': { + $id: '/schemas/protocol/get-adcp-capabilities-response.json', + type: 'object', + properties: { + media_buy: { + type: 'object', + properties: { + conversion_tracking: { type: 'object' }, + execution: { $ref: '/schemas/core/execution.json' }, + }, + }, + }, + }, +}; + +function product(properties, extra = {}) { + return { + 'core/product.json': { + $id: '/schemas/core/product.json', + type: 'object', + properties, + ...extra, + }, + }; +} + +function withFixture(files, callback) { + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'applies-when-')); + try { + for (const [relativePath, schema] of Object.entries({ ...BASE_FILES, ...files })) { + writeJson(tmp, relativePath, schema); + } + callback(lintAppliesWhen({ schemasDir: tmp })); + } finally { + fs.rmSync(tmp, { recursive: true, force: true }); + } +} + +function assertErrorMatching(result, pattern) { + assert.equal(result.ok, false, 'expected the lint to fail'); + assert.ok( + result.errors.some((error) => pattern.test(error)), + `expected an error matching ${pattern}, got:\n${result.errors.join('\n')}`, + ); +} + +test('the repository source tree passes', () => { + const result = lintAppliesWhen(); + assert.equal(result.ok, true, result.errors.join('\n')); + assert.ok(result.annotations.length > 0, 'expected annotated properties'); +}); + +test('accepts every key, including capability paths that cross a $ref', () => { + withFixture(product({ + cancellation_policy: { type: 'object', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } }, + cpp_terms: { type: 'object', 'x-adcp-applies-when': { pricing_models: ['cpp'] } }, + trusted_match: { + type: 'object', + 'x-adcp-applies-when': { capabilities: ['media_buy.execution.trusted_match'] }, + }, + tracking: { + type: 'object', + 'x-adcp-applies-when': { + delivery_types: ['non_guaranteed'], + capabilities: ['media_buy.conversion_tracking'], + }, + }, + }), (result) => { + assert.equal(result.ok, true, result.errors.join('\n')); + assert.equal(result.annotations.length, 4); + }); +}); + +test('rejects unknown keys', () => { + withFixture(product({ + field: { type: 'string', 'x-adcp-applies-when': { channels: ['dooh'] } }, + }), (result) => assertErrorMatching(result, /unknown key "channels"/)); +}); + +test('rejects empty annotations and empty arrays', () => { + withFixture(product({ + a: { type: 'string', 'x-adcp-applies-when': {} }, + b: { type: 'string', 'x-adcp-applies-when': { delivery_types: [] } }, + }), (result) => { + assertErrorMatching(result, /must name at least one key/); + assertErrorMatching(result, /delivery_types must be a non-empty array/); + }); +}); + +test('rejects values outside their enums', () => { + withFixture(product({ + a: { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guarenteed'] } }, + b: { type: 'string', 'x-adcp-applies-when': { pricing_models: ['cpx'] } }, + }), (result) => { + assertErrorMatching(result, /"guarenteed" is not in enums\/delivery-type\.json/); + assertErrorMatching(result, /"cpx" is not in enums\/pricing-model\.json/); + }); +}); + +test('rejects capability paths that do not resolve', () => { + withFixture(product({ + a: { type: 'string', 'x-adcp-applies-when': { capabilities: ['media_buy.execution.nope'] } }, + }), (result) => assertErrorMatching(result, /"media_buy\.execution\.nope" does not resolve/)); +}); + +test('rejects annotated properties that the parent requires', () => { + withFixture(product( + { a: { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } } }, + { required: ['a'] }, + ), (result) => assertErrorMatching(result, /"a" is required by its parent/)); +}); + +test('treats unconditional allOf required as required, but not if/then', () => { + const annotated = { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } }; + withFixture(product({ a: annotated }, { allOf: [{ required: ['a'] }] }), (result) => + assertErrorMatching(result, /"a" is required by its parent/)); + withFixture(product({ a: annotated }, { + allOf: [{ if: { required: ['b'] }, then: { required: ['a'] } }], + }), (result) => assert.equal(result.ok, true, result.errors.join('\n'))); +}); + +test('rejects the annotation outside a property declaration', () => { + withFixture(product({ + list: { + type: 'array', + items: { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } }, + }, + }), (result) => assertErrorMatching(result, /must sit on a property declaration/)); +}); + +test('ignores annotation-shaped values inside examples', () => { + withFixture(product({ + a: { type: 'object', examples: [{ 'x-adcp-applies-when': { bogus: true } }] }, + }), (result) => assert.equal(result.ok, true, result.errors.join('\n'))); +}); From b993d4ad8cd10f83077e5e05e38c028fcd2f0c14 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 24 Oct 2026 22:14:27 +0000 Subject: [PATCH 4/5] fix(schema): tighten x-adcp-applies-when semantics after seat review Product and protocol seat reviews of RFC #8452 found: - Define dropping: it deletes a property from properties and nothing else. A projection never changes additionalProperties or removes enum values, and receivers read every payload against the canonical schema. This replaces the false claim that projection-valid implies canonical-valid. - Never annotate a property of a closed object, since dropping it there forbids it. canonical-pricing-option is closed, so its tags are removed, and the lint now rejects this case. - Fail open only for the delivery_types and pricing_models lists. A capabilities path matches only when present, not null, and not false. - Count conditional requirements (if/then/else, union arms, draft-07 dependencies) as required, failing closed. This surfaced product.conversion_tracking, which the product conditionally requires, so it is no longer annotated. - Untag product.cancellation_policy. Non-guaranteed buys carry notice terms too. - Document nesting, reading before dereferencing, union-arm selection, and accepted records. Lead with coverage tooling; narrowing is optional. Refs #8452. Co-Authored-By: Claude Opus 5.5 (1M context) --- .changeset/x-adcp-applies-when.md | 2 +- docs/reference/migration/3-2-to-3-3.mdx | 2 +- docs/reference/schema-extensions.mdx | 35 ++++++++++++------- docs/reference/whats-new-in-3-3.mdx | 2 +- scripts/lint-applies-when.cjs | 33 ++++++++++++----- .../source/core/canonical-pricing-option.json | 4 +-- static/schemas/source/core/product.json | 2 -- tests/lint-applies-when.test.cjs | 23 ++++++++++-- 8 files changed, 73 insertions(+), 30 deletions(-) diff --git a/.changeset/x-adcp-applies-when.md b/.changeset/x-adcp-applies-when.md index 2f19b3a5bf5..26fdec09193 100644 --- a/.changeset/x-adcp-applies-when.md +++ b/.changeset/x-adcp-applies-when.md @@ -2,4 +2,4 @@ "adcontextprotocol": minor --- -Add the `x-adcp-applies-when` schema annotation (#8452). It names the capability declarations (`delivery_types`, `pricing_models`, `capabilities` paths) that make a property relevant, and never changes validation. Projections, such as a non-guaranteed-only MCP tool surface, use it to drop optional fields from one canonical schema. Initial annotations cover `product.cancellation_policy` (guaranteed), `floor_price` and `price_guidance` on pricing options (non_guaranteed), and the product's conversion-tracking, vendor-metric-optimization, and Trusted Match fields (their capability blocks). `scripts/lint-applies-when.cjs` checks every annotation. +Add the `x-adcp-applies-when` schema annotation (#8452). It names the capability declarations (`delivery_types`, `pricing_models`, `capabilities` paths) that make a property relevant, and never changes validation. Projections, such as a guaranteed-only MCP tool surface, use it to drop optional fields from one canonical schema. Initial annotations cover `floor_price` and `price_guidance` on pricing options (non_guaranteed), and the product's `measurement_readiness`, `vendor_metric_optimization`, and `trusted_match` fields (their capability blocks). `product.conversion_tracking` stays unannotated because the product conditionally requires it. `scripts/lint-applies-when.cjs` checks every annotation. diff --git a/docs/reference/migration/3-2-to-3-3.mdx b/docs/reference/migration/3-2-to-3-3.mdx index 3ad2210be4b..d8297ccdc92 100644 --- a/docs/reference/migration/3-2-to-3-3.mdx +++ b/docs/reference/migration/3-2-to-3-3.mdx @@ -535,7 +535,7 @@ The field is stable in 3.3, not experimental. It completes the basis vocabulary ### Catalogs, signing, and extensions -- **Delivery types.** Declare `media_buy.supported_delivery_types` with the delivery types you sell, and return only products whose `delivery_type` is listed. Buyers treat an absent declaration as unknown, not as an empty set. Projections, such as a non-guaranteed-only MCP tool surface, resolve the `x-adcp-applies-when` schema annotation against this field and the other capability blocks; the annotation never changes validation. See [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when). +- **Delivery types.** Declare `media_buy.supported_delivery_types` with the delivery types you sell, and return only products whose `delivery_type` is listed. Buyers treat an absent declaration as unknown, not as an empty set. Projections, such as a guaranteed-only MCP tool surface, resolve the `x-adcp-applies-when` schema annotation against this field and the other capability blocks; the annotation never changes validation. See [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when). - **Catalog ingestion.** Declare `media_buy.features.catalog_ingestion` with `accepted_catalog_types`, `ingestion_modes`, and `item_status_reporting` (required), plus `supported_feed_formats` whenever `feed_url` is listed. Declaring it requires `catalog_management: true`. Reject an unlisted catalog type, mode, or feed format, or an explicit `content_id_type` outside a declared list, with `UNSUPPORTED_FEATURE` before mutation, including on `dry_run`; inline items beyond `max_inline_items_per_request` fail with `INVALID_REQUEST`. Buyers treat an absent declaration as unknown, not unrestricted. See [`sync_catalogs`](/docs/media-buy/task-reference/sync_catalogs#ingestion-compatibility). - **`request_signing.operation_sources`.** List `mcp_tools_call` and `a2a_invocation_skill` only for the sources your verifier implements and passes vectors for, and list every source you support: an array without `a2a_invocation_skill` tells peers you do not enforce over A2A. See [above](#a2a-operation-resolution-hardening-becomes-must). - **`trust.json` (experimental).** `trust/v1/trust.json` and `trust/v1/trust-acknowledgements.json` are published under `identity.trust_json` (#8067). An agent is identified by the canonical origin of its URL, one agent per origin, and the record carries no keys (#8121). In 3.3 its reader is the experimental Web Bot Auth profile, which derives the record from the agent's origin, and grants are read at `sync_accounts`. Publishers declare nothing. See [trust.json](/docs/reference/trust-json) and the [agent identity migration guide](/docs/reference/migration/agent-identity-3-3). diff --git a/docs/reference/schema-extensions.mdx b/docs/reference/schema-extensions.mdx index b018e5bdc56..45294bbb791 100644 --- a/docs/reference/schema-extensions.mdx +++ b/docs/reference/schema-extensions.mdx @@ -161,12 +161,13 @@ Adding `x-adcp-hoist` to a previously-inlined source schema is wire-compatible ( Names the seller capability declarations that make a property relevant. The annotation is documentary and non-validating: the property's JSON Schema still controls wire validation, and validators MUST ignore the keyword. -It exists so a seller can expose a narrower surface without a seller-specific schema or SDK. For example, a seller that sells only non-guaranteed inventory can drop guaranteed-only fields from its MCP tool schemas. Such a narrowed schema is a **projection**: a pure function of one canonical schema and the seller's own [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) response. Docs and storyboard coverage checks read the same annotation. +It records which capability makes a field meaningful, so tooling can read that from the schema instead of from prose. Storyboard coverage checks can confirm that a declared capability's fields are exercised, docs can group fields by capability, and a seller can expose a narrower surface without a seller-specific schema or SDK. For example, a seller that sells only guaranteed inventory can drop auction-only fields from its MCP tool schemas. Such a narrowed schema is a **projection**: a pure function of one canonical schema and the seller's own [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) response. A seller that declares both delivery types gets no narrowing from `delivery_types` annotations; that is expected, because projections only ever remove fields. ```jsonc -"cancellation_policy": { - "x-adcp-applies-when": { "delivery_types": ["guaranteed"] }, - "$ref": "/schemas/core/cancellation-policy.json" +"floor_price": { + "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] }, + "type": "number", + "minimum": 0 } ``` @@ -178,35 +179,43 @@ The value is an object with one or more of these keys. Each key holds a non-empt |---|---|---| | `delivery_types` | [`delivery-type`](https://adcontextprotocol.org/schemas/v3/enums/delivery-type.json) values | `media_buy.supported_delivery_types` | | `pricing_models` | [`pricing-model`](https://adcontextprotocol.org/schemas/v3/enums/pricing-model.json) values | `media_buy.supported_pricing_models` | -| `capabilities` | Dotted paths into the `get_adcp_capabilities` response, such as `media_buy.conversion_tracking` | Satisfied when the path is present and not `false` | +| `capabilities` | Dotted paths into the `get_adcp_capabilities` response, such as `media_buy.conversion_tracking` | Satisfied when the path is present, not `null`, and not `false` | There is no `channels` key yet. `portfolio.primary_channels` is a brief-routing scope, not an exhaustive declaration of the channels a seller sells. ### Semantics - **Any match counts.** The property is relevant when any listed value matches the seller's declaration. A projection that can't express both conditions together, such as "guaranteed and proposals", keeps more fields than it needs, never fewer. -- **Fail open.** When the seller hasn't declared the matched capability, for example it omits `supported_delivery_types`, the property stays relevant. -- **Projections only remove.** A projection MAY drop optional properties whose annotation doesn't match. It MUST NOT rename, retype, or add required properties. A payload valid against a projection is valid against the canonical schema. -- **Never on required properties.** A property that carries the annotation MUST NOT be listed in its parent's `required`. -- **Union arms need no annotation.** Arms of a discriminated union, such as the pricing options keyed by `pricing_model`, are already selected by their discriminator. +- **Fail open on undeclared lists.** When `media_buy.supported_delivery_types` is absent, `delivery_types` matches; when `media_buy.supported_pricing_models` is absent, `pricing_models` matches. A `capabilities` path matches only when the path is present, not `null`, and not `false`. Absence does not match, because these capability blocks declare support by being present. +- **Dropping only deletes.** Dropping a property deletes it from `properties` and changes nothing else. A projection MUST NOT rename, retype, or add required properties, MUST NOT change `additionalProperties`, and MUST NOT remove enum values; this annotation doesn't key enum values. +- **Receivers read the canonical schema.** Receivers interpret every payload against the canonical schema. A receiver MUST NOT reject a property, ignore it as unknown, or reinterpret it because the sender's projection dropped it. +- **Never on required properties.** A property that carries the annotation MUST NOT be listed in its parent's `required`, including conditional requirements in `allOf`, `anyOf`, or `oneOf` arms, `if`/`then`/`else` branches, and draft-07 `dependencies`. Dropping a conditionally required property would leave a projection that can't be satisfied when the condition holds. +- **Never in closed objects.** The annotation MUST NOT appear on a property whose parent schema sets `additionalProperties: false`. Deleting a property from a closed object forbids it, which is a tightening. +- **Nesting and context.** A property is relevant only when its own annotation and every ancestor property's annotation match. Every key is seller-global, so a schema reached by `$ref` projects the same way in every context. +- **Read before dereferencing.** In draft-07, keywords beside `$ref` are ignored by validators. Consumers read the annotation from the property declaration before following its `$ref`. +- **Union arms need no annotation.** Arms of a discriminated union, such as the pricing options keyed by `pricing_model`, are already selected by their discriminator. An annotated property MUST NOT take part in selecting an arm of an enclosing `oneOf` or `anyOf`. +- **Accepted records.** Projections SHOULD NOT be applied to schemas of records the buyer has already accepted, such as committed proposal or media-buy snapshots. A seller's capabilities can change after acceptance, and projecting the record would hide terms the buyer agreed to. ### Conformance - Validators MUST ignore `x-adcp-applies-when`. Projection is optional: a seller that exposes the full canonical surface is conformant. -- `scripts/lint-applies-when.cjs` checks every annotation: only known keys, non-empty arrays, values valid against their enums, every capability path resolving in `get-adcp-capabilities-response.json`, and no annotated property listed as required. +- `scripts/lint-applies-when.cjs` checks every annotation: it sits on a property declaration; it uses only known keys, with non-empty arrays of unique values valid against their enums; every capability path resolves in `get-adcp-capabilities-response.json`; the parent doesn't require the property anywhere (it fails closed, so a name that appears only in an `if` condition counts too); and the parent isn't closed. ### Current usage | Property | Annotation | |---|---| -| `product.cancellation_policy` | `delivery_types: ["guaranteed"]` | -| `floor_price`, `price_guidance` on each pricing option that has them, and on `canonical-pricing-option` | `delivery_types: ["non_guaranteed"]` | -| `product.conversion_tracking`, `product.measurement_readiness` | `capabilities: ["media_buy.conversion_tracking"]` | +| `floor_price`, `price_guidance` on each pricing option that has them | `delivery_types: ["non_guaranteed"]` | +| `product.measurement_readiness` | `capabilities: ["media_buy.conversion_tracking"]` | | `product.vendor_metric_optimization` | `capabilities: ["media_buy.vendor_metric_optimization"]` | | `product.trusted_match` | `capabilities: ["media_buy.execution.trusted_match"]` | `fixed_price` is deliberately not annotated: non-guaranteed broadcast scatter and PMP deals are fixed-price too. +`product.conversion_tracking` is not annotated either: the product requires it whenever an execution requirement names an event source. Nor is `product.cancellation_policy`: non-guaranteed buys carry notice terms too, and a projection that dropped it would leave a non-guaranteed seller unable to state them. + +On `floor_price` and `price_guidance`, `delivery_types: ["non_guaranteed"]` stands in for auction pricing, since guaranteed products are not auctioned. + ### History - Introduced in 3.3 by [#8452](https://github.com/adcontextprotocol/adcp/issues/8452), from the [#8359](https://github.com/adcontextprotocol/adcp/issues/8359) discussion. diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index 410728f2705..5d264cdd455 100644 --- a/docs/reference/whats-new-in-3-3.mdx +++ b/docs/reference/whats-new-in-3-3.mdx @@ -112,7 +112,7 @@ Two more guarantees loosen here, and the response-size default a third ([below]( - **Signal readiness (experimental).** `get_signals` results can carry `signal_status` (`processing`, `ready`, `failed`) and the `source_audience_id` a custom segment was built from. Feature id `signals.signal_lifecycle`. See [Custom segments built from a seed audience](/docs/signals/tasks/get_signals#custom-segments-built-from-a-seed-audience). - **Event source archive.** A seller that declares `media_buy.event_source_archive` accepts `archived` on `sync_event_sources` items to archive or restore a source without losing its configuration. See [Archiving an event source](/docs/media-buy/task-reference/sync_event_sources#archiving-an-event-source). - **Creative and brand.** `list_creatives` echoes creative-level `provenance`; brand.json gains a brand-wide `prohibited_terms` list; rights constraints can carry advisory `channels[]` and `excluded_channels[]` (experimental, `brand.rights_lifecycle`); and the HTML-markup legacy formats project to `display_tag` inline markup instead of `html5`. -- **Delivery types.** `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` inventory, `non_guaranteed` inventory, or both, so buyers can skip sellers that don't sell what they're buying before calling `get_products`. A declaring seller returns only products with a listed `delivery_type`. The `x-adcp-applies-when` schema annotation names the capability that makes a field relevant, for example `floor_price` for `non_guaranteed` and `cancellation_policy` for `guaranteed`, so a seller can expose a narrower tool surface derived from one canonical schema. The annotation never changes validation. See [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when). +- **Delivery types.** `media_buy.supported_delivery_types` declares whether a seller sells `guaranteed` inventory, `non_guaranteed` inventory, or both, so buyers can skip sellers that don't sell what they're buying before calling `get_products`. A declaring seller returns only products with a listed `delivery_type`. The `x-adcp-applies-when` schema annotation names the capability that makes a field relevant, for example `floor_price` for `non_guaranteed`, so a seller can expose a narrower tool surface derived from one canonical schema. The annotation never changes validation. See [`x-adcp-applies-when`](/docs/reference/schema-extensions#x-adcp-applies-when). - **The `ext.adcp` namespace.** `ext.adcp` is a registered, AdCP-owned extension namespace. Its first member is an optional `opportunity` binding for cooperating 3.2 `get_products` integrations. See [AdCP opportunity extension](/docs/building/by-layer/L2/context-sessions#adcp-opportunity-extension). ## Bounded agent responses diff --git a/scripts/lint-applies-when.cjs b/scripts/lint-applies-when.cjs index 0482b664d76..96118cba6ad 100644 --- a/scripts/lint-applies-when.cjs +++ b/scripts/lint-applies-when.cjs @@ -57,14 +57,27 @@ function loadEnum(registry, relativePath, errors) { return new Set(document.schema.enum); } -/** Unconditional `required` names: the parent's own plus allOf arms without `if`. */ -function requiredNames(parent) { - const names = new Set(Array.isArray(parent.required) ? parent.required : []); - if (Array.isArray(parent.allOf)) { - for (const arm of parent.allOf) { - if (isObject(arm) && !('if' in arm) && Array.isArray(arm.required)) { - arm.required.forEach((name) => names.add(name)); - } +/** + * Names the parent requires anywhere: its own `required`, every + * allOf/anyOf/oneOf arm, if/then/else branch, and draft-07 `dependencies`. + * Conditional requirements count too, and so do names that appear only in an + * `if` condition. A projection that drops a conditionally required property leaves + * a schema that can't be satisfied when the condition holds, so this fails + * closed. + */ +function requiredNames(parent, names = new Set()) { + if (!isObject(parent)) return names; + if (Array.isArray(parent.required)) parent.required.forEach((name) => names.add(name)); + for (const keyword of ['allOf', 'anyOf', 'oneOf']) { + if (Array.isArray(parent[keyword])) { + parent[keyword].forEach((arm) => requiredNames(arm, names)); + } + } + for (const keyword of ['if', 'then', 'else']) requiredNames(parent[keyword], names); + if (isObject(parent.dependencies)) { + for (const dependency of Object.values(parent.dependencies)) { + if (Array.isArray(dependency)) dependency.forEach((name) => names.add(name)); + else requiredNames(dependency, names); } } return names; @@ -172,6 +185,7 @@ function collectAnnotations(registry) { pointer: propertyPointer, value: propertySchema[ANNOTATION], required: required.has(name), + closed: node.additionalProperties === false, }); } visit(propertySchema, document, propertyPointer, true); @@ -209,6 +223,9 @@ function lintAppliesWhen({ schemasDir = DEFAULT_SCHEMAS_DIR } = {}) { if (annotation.required) { errors.push(`${location}: annotated property "${annotation.name}" is required by its parent; projections may only remove optional properties`); } + if (annotation.closed) { + errors.push(`${location}: annotated property "${annotation.name}" sits in a closed object (additionalProperties: false); dropping it would forbid it`); + } } return { ok: errors.length === 0, errors, annotations }; diff --git a/static/schemas/source/core/canonical-pricing-option.json b/static/schemas/source/core/canonical-pricing-option.json index 09b7ed130d2..951c9e2f2d0 100644 --- a/static/schemas/source/core/canonical-pricing-option.json +++ b/static/schemas/source/core/canonical-pricing-option.json @@ -12,8 +12,8 @@ }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fixed_price": { "type": "number", "minimum": 0 }, - "floor_price": { "type": "number", "minimum": 0, "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] } }, - "price_guidance": { "$ref": "/schemas/pricing-options/price-guidance.json", "x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] } }, + "floor_price": { "type": "number", "minimum": 0 }, + "price_guidance": { "$ref": "/schemas/pricing-options/price-guidance.json" }, "min_spend_per_package": { "type": "number", "minimum": 0 }, "price_breakdown": { "$ref": "/schemas/pricing-options/price-breakdown.json" }, "eligible_adjustments": { diff --git a/static/schemas/source/core/product.json b/static/schemas/source/core/product.json index b050ef65c8a..c505131a425 100644 --- a/static/schemas/source/core/product.json +++ b/static/schemas/source/core/product.json @@ -168,7 +168,6 @@ "minItems": 1 }, "cancellation_policy": { - "x-adcp-applies-when": { "delivery_types": ["guaranteed"] }, "$ref": "/schemas/core/cancellation-policy.json", "description": "Cancellation terms for this product. Declares the minimum notice period required before cancellation takes effect and any penalties for insufficient notice. Relevant for guaranteed delivery products. Buyers accept these terms by creating a media buy against the product." }, @@ -375,7 +374,6 @@ "description": "Assessment of whether the buyer's event source setup is sufficient for this product to optimize effectively. Only present when the seller can evaluate the buyer's account context. Buyers should check this before creating media buys with event-based optimization goals." }, "conversion_tracking": { - "x-adcp-applies-when": { "capabilities": ["media_buy.conversion_tracking"] }, "type": "object", "description": "Conversion event tracking for this product. Presence indicates the product supports optimization_goals with kind: 'event'. Seller-level capabilities (supported event types, UID types, attribution windows) are declared in get_adcp_capabilities.", "properties": { diff --git a/tests/lint-applies-when.test.cjs b/tests/lint-applies-when.test.cjs index 3348131074a..6de5d0a3169 100644 --- a/tests/lint-applies-when.test.cjs +++ b/tests/lint-applies-when.test.cjs @@ -144,13 +144,32 @@ test('rejects annotated properties that the parent requires', () => { ), (result) => assertErrorMatching(result, /"a" is required by its parent/)); }); -test('treats unconditional allOf required as required, but not if/then', () => { +test('treats allOf, oneOf, and conditional requirements as required', () => { const annotated = { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } }; withFixture(product({ a: annotated }, { allOf: [{ required: ['a'] }] }), (result) => assertErrorMatching(result, /"a" is required by its parent/)); + withFixture(product({ a: annotated }, { oneOf: [{ required: ['a'] }, { required: ['b'] }] }), (result) => + assertErrorMatching(result, /"a" is required by its parent/)); withFixture(product({ a: annotated }, { allOf: [{ if: { required: ['b'] }, then: { required: ['a'] } }], - }), (result) => assert.equal(result.ok, true, result.errors.join('\n'))); + }), (result) => assertErrorMatching(result, /"a" is required by its parent/)); + withFixture(product({ a: annotated }, { if: { required: ['b'] }, else: { required: ['a'] } }), (result) => + assertErrorMatching(result, /"a" is required by its parent/)); +}); + +test('counts draft-07 dependencies as requirements', () => { + const annotated = { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } }; + withFixture(product({ a: annotated, b: { type: 'string' } }, { dependencies: { b: ['a'] } }), (result) => + assertErrorMatching(result, /"a" is required by its parent/)); + withFixture(product({ a: annotated, b: { type: 'string' } }, { dependencies: { b: { required: ['a'] } } }), (result) => + assertErrorMatching(result, /"a" is required by its parent/)); +}); + +test('rejects annotated properties in closed objects', () => { + withFixture(product( + { a: { type: 'string', 'x-adcp-applies-when': { delivery_types: ['guaranteed'] } } }, + { additionalProperties: false }, + ), (result) => assertErrorMatching(result, /sits in a closed object/)); }); test('rejects the annotation outside a property declaration', () => { From 193a663ac918c9f7b0b65d8e1d0217990a1c94c3 Mon Sep 17 00:00:00 2001 From: Brian O'Kelley Date: Sat, 24 Oct 2026 22:32:36 +0000 Subject: [PATCH 5/5] fix(schema): resolve x-adcp-applies-when against the agent's own capabilities The adcp-client prototype (adcontextprotocol/adcp-client#3415) found that shared schemas reach other agents' tools: a governance agent's check_governance request embeds products and pricing options, but that agent publishes no media_buy block. A key whose root capability block the agent doesn't publish now matches, so the property is kept. Refs #8452. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/reference/schema-extensions.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/reference/schema-extensions.mdx b/docs/reference/schema-extensions.mdx index 45294bbb791..cbbdb8ff88b 100644 --- a/docs/reference/schema-extensions.mdx +++ b/docs/reference/schema-extensions.mdx @@ -187,6 +187,7 @@ There is no `channels` key yet. `portfolio.primary_channels` is a brief-routing - **Any match counts.** The property is relevant when any listed value matches the seller's declaration. A projection that can't express both conditions together, such as "guaranteed and proposals", keeps more fields than it needs, never fewer. - **Fail open on undeclared lists.** When `media_buy.supported_delivery_types` is absent, `delivery_types` matches; when `media_buy.supported_pricing_models` is absent, `pricing_models` matches. A `capabilities` path matches only when the path is present, not `null`, and not `false`. Absence does not match, because these capability blocks declare support by being present. +- **Projections use the agent's own capabilities.** A projection narrows an agent's own tool schemas against that agent's own `get_adcp_capabilities` response. When the agent publishes no block at the key's root at all, the key matches. For example, a governance agent has no `media_buy` block, so a `media_buy.*` key keeps the property in a product embedded in its `check_governance` request. - **Dropping only deletes.** Dropping a property deletes it from `properties` and changes nothing else. A projection MUST NOT rename, retype, or add required properties, MUST NOT change `additionalProperties`, and MUST NOT remove enum values; this annotation doesn't key enum values. - **Receivers read the canonical schema.** Receivers interpret every payload against the canonical schema. A receiver MUST NOT reject a property, ignore it as unknown, or reinterpret it because the sender's projection dropped it. - **Never on required properties.** A property that carries the annotation MUST NOT be listed in its parent's `required`, including conditional requirements in `allOf`, `anyOf`, or `oneOf` arms, `if`/`then`/`else` branches, and draft-07 `dependencies`. Dropping a conditionally required property would leave a projection that can't be satisfied when the condition holds.