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/.changeset/x-adcp-applies-when.md b/.changeset/x-adcp-applies-when.md new file mode 100644 index 00000000000..26fdec09193 --- /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 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/.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 71bdd3e11ea..4ba234775bc 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`. 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 4f4532aa65b..d8297ccdc92 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. 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 ab18cef659f..cbbdb8ff88b 100644 --- a/docs/reference/schema-extensions.mdx +++ b/docs/reference/schema-extensions.mdx @@ -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. diff --git a/docs/reference/whats-new-in-3-3.mdx b/docs/reference/whats-new-in-3-3.mdx index d63c962be65..5d264cdd455 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 `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/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..96118cba6ad --- /dev/null +++ b/scripts/lint-applies-when.cjs @@ -0,0 +1,260 @@ +#!/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); +} + +/** + * 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; +} + +/** + * 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), + closed: node.additionalProperties === false, + }); + } + 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`); + } + 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 }; +} + +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/product.json b/static/schemas/source/core/product.json index a64213afc35..c505131a425 100644 --- a/static/schemas/source/core/product.json +++ b/static/schemas/source/core/product.json @@ -359,6 +359,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,6 +369,7 @@ "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." }, @@ -565,6 +567,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/static/schemas/source/protocol/get-adcp-capabilities-response.json b/static/schemas/source/protocol/get-adcp-capabilities-response.json index 2e7b873073c..eaf53378159 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. 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" + }, + "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.", diff --git a/tests/lint-applies-when.test.cjs b/tests/lint-applies-when.test.cjs new file mode 100644 index 00000000000..6de5d0a3169 --- /dev/null +++ b/tests/lint-applies-when.test.cjs @@ -0,0 +1,188 @@ +#!/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 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) => 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', () => { + 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'))); +});