Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/supported-delivery-types.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions .changeset/x-adcp-applies-when.md
Original file line number Diff line number Diff line change
@@ -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 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.
3 changes: 3 additions & 0 deletions .github/workflows/build-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions docs/protocol/capabilities-explorer.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`. 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)

Expand Down
1 change: 1 addition & 0 deletions docs/reference/migration/3-2-to-3-3.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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. 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).
Expand Down
64 changes: 64 additions & 0 deletions docs/reference/schema-extensions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,70 @@ 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 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
"floor_price": {
"x-adcp-applies-when": { "delivery_types": ["non_guaranteed"] },
"type": "number",
"minimum": 0
}
```

### 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, 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 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.
- **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: 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 |
|---|---|
| `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.

## 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.
1 change: 1 addition & 0 deletions docs/reference/whats-new-in-3-3.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 `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
Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Loading
Loading