Skip to content
Merged
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
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
22 changes: 22 additions & 0 deletions .changeset/open-closed-schemas-3-2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
"adcontextprotocol": patch
---

Open the 3.2 schemas that were closed by accident, so a 3.2 validator no longer rejects a newer 3.x payload because it carries a field 3.2 does not know. Backports the 3.3 opening decided by the working group on 2026-11-09.

`additionalProperties` goes from `false` to `true` at 674 of the 775 closed locations in the 3.2 source tree.

101 locations stay closed, matching 3.3: most for a structural reason, and the commercial terms as a hold until 4.0.

- `oneOf` branches told apart only by which keys are present (`a2ui/bound-value.json`, `brand.json`).
- Metric qualifiers and forecast dimensions, which consumers join on.
- The JWS response envelope.
- Privacy boundaries: the TMP match requests, the not-found error, the per-agent permission-denied and billing-not-permitted details, the `get_principal` recognized, unconfigured and failed results, the failed `sync_principal` result, and the `get_reporting_status` unavailable-lookup result.
- The credential-free reporting destinations and the destination `setup` action.
- `placement-presentation`, which carries no key material or markup.
- `patternProperties` maps keyed by IDs.
- Held closed until 4.0: the commercial terms and the hard `proposal-budget-constraint`. This is a hold, not a structural reason; 4.0 gives `commercial_terms` a declared extension point with must-understand.

Where closure was the only thing rejecting a specific field that the protocol defines elsewhere or forbids (for example `trackers` on `unassign`, `staged_update` on `creative.status_changed`, `auth_token` on list-application receipts, or credentials on a notification-config readback), the opened schema now rejects that field by name with `not`. `access_token` on the delivery-ready webhook is rejected as a credential clamp. The same applies to unions whose branches were told apart only by which keys are present: an account ref, compact or not, carries `account_id` or the natural key, not both; a geo-region country entry carries `all_values` or `values`; image bleed is uniform or per-side; a deprecated fused-system postal area carries no `country`; and a reporting-receipt result carries `receipt` or `adjustment_receipt`, a failed one neither. Each node with a named rejection says in its description what it rejects and why, since generated types cannot express `not`. Descriptions of opened schemas no longer say they are closed.

The MCP model-context projection now omits `additionalProperties: true` as well as `false`, since `true` is the JSON Schema default.
2 changes: 1 addition & 1 deletion docs/governance/campaign/specification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -898,7 +898,7 @@ Closed list — governance agents MUST NOT extend or shrink it; any addition is
- `committedBudget` — derived from downstream `check_governance` / `report_plan_outcome` activity
- `committedByType` — derived from the same activity

None of these appear in the `sync_plans` request schema (`additionalProperties: false` on the plan item); they exist only on the governance agent's persisted plan state. The list is stated explicitly so an implementer naively hashing their internal state struct strips the right fields. Implementations that discover additional GA-internal fields on their persisted plan state beyond this list MUST treat those fields as **IN the preimage** until the profile version bumps — fail-safe toward inclusion, not exclusion. The "anything that looks like bookkeeping → strip" shortcut silently diverges every implementation that guesses differently; the safe default is "if it is not on the closed list, it is part of the hash."
None of these is a `sync_plans` request field; they exist only on the governance agent's persisted plan state. The list is stated explicitly so an implementer naively hashing their internal state struct strips the right fields. Implementations that discover additional GA-internal fields on their persisted plan state beyond this list MUST treat those fields as **IN the preimage** until the profile version bumps — fail-safe toward inclusion, not exclusion. The "anything that looks like bookkeeping → strip" shortcut silently diverges every implementation that guesses differently; the safe default is "if it is not on the closed list, it is part of the hash."

All other fields — including `ext`, `custom_policies`, `objectives`, `delegations`, `human_override`, and every field declared in the `sync_plans` plan-item schema — are IN the preimage. Caller guidance:

Expand Down
2 changes: 1 addition & 1 deletion docs/governance/content-standards/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ Content Standards uses **addressable policies** — an array of policy entries,
| `exemplars` | No | Structured `pass` and `fail` scenarios used to calibrate policy interpretation. |
| `ext` | No | Vendor-namespaced extension data for partner-specific metadata. |

Policy entries are closed objects: fields outside this table fail schema validation rather than being silently ignored. Put partner-specific, buyer-visible metadata under a vendor key in `ext` (for example, `ext.acme`) instead of adding sibling fields or encoding structured metadata inside the natural-language `policy` value.
Fields outside this table aren't part of a policy entry, and readers ignore them. Put partner-specific, buyer-visible metadata under a vendor key in `ext` (for example, `ext.acme`) instead of adding sibling fields or encoding structured metadata inside the natural-language `policy` value.

```json
{
Expand Down
7 changes: 3 additions & 4 deletions docs/media-buy/product-discovery/refinement.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -329,13 +329,12 @@ Client implementations should validate refinement requests against the [request
| `MULTI_FINALIZE_UNSUPPORTED` | `refine[]` carried multiple `action: 'finalize'` entries but the seller cannot guarantee atomic multi-proposal commit | Sequence single-proposal finalize calls (one finalize per `get_products` call) |
| `INVALID_REQUEST` | `refine` provided in `brief` or `wholesale` mode, empty `refine` array, or missing required fields | Check `buying_mode` and required fields |

### Troubleshooting: "must NOT have additional properties" on `refine[].id`
### Troubleshooting: "must have required property 'product_id'" on `refine[]`

Each scope branch in `refine[]` is `additionalProperties: false`, which means a stray `id` field from the pre-3.0-rc refine shape is rejected — not silently ignored — with an error along the lines of:
The `product` scope requires `product_id` and the `proposal` scope requires `proposal_id` (the `request` scope requires `ask` instead). So an entry that carries only the generic `id` field from the pre-3.0-rc refine shape is rejected, with an error along the lines of:

```
/refine/0: must NOT have additional properties { additionalProperty: "id" }
/refine/0: must match oneOf schema { required: ["product_id"] }
/refine/0: must have required property 'product_id'
```

If you see this, an orchestrator is still constructing product or proposal refine entries with the generic `id` field. Rename to `product_id` under `scope: "product"` and `proposal_id` under `scope: "proposal"`. See the [task reference](/docs/media-buy/task-reference/get_products#refine-array) for the current shape. The same rename applies to `refinement_applied[]` if you're echoing on the seller side.
Expand Down
6 changes: 3 additions & 3 deletions docs/protocol/calling-an-agent.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ For the key-required operations listed above, a missing key produces `adcp_error
"account": { "brand": { "domain": "acme.com" }, "operator": "pinnacle-media.com" }
```

**Do NOT merge required fields across variants.** `additionalProperties: false` on each variant means `{account_id, brand}` fails BOTH.
**Do NOT merge required fields across variants.** Each variant rejects the other's fields, so `{account_id, brand}` fails BOTH.

When a task schema requires `account`, send an explicit `AccountRef` even if the SDK auto-selected the only account available to the authenticated credential. Hidden credential-implied defaulting is not a protocol model. When a task marks `account` optional, omission has only the semantics documented by that task.

Expand Down Expand Up @@ -157,9 +157,9 @@ Every validation failure produces an envelope shaped like:
| Symptom | What it means | Fix |
|---|---|---|
| `keyword: 'oneOf'` with `variants[]` | Discriminated union — you sent fields from multiple variants, or none | Pick ONE variant from `variants[]`. Send only its `required` fields. |
| 2-3 `additionalProperties` errors at the same pointer | You merged `oneOf` variants | Drop to one variant. Don't keep "extra" fields "for completeness". |
| 2-3 `not` or `required` errors at the same pointer | You merged `oneOf` variants | Drop to one variant. Don't keep "extra" fields "for completeness". |
| `keyword: 'required'`, `pointer: '/idempotency_key'` | Mutating tool, no UUID | Generate fresh UUID per logical operation. Reuse on retries. |
| `keyword: 'type'` or `additionalProperties` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |
| `keyword: 'type'` at `/budget` | Sent `{amount, currency}` | `budget` is a number. Currency is implied by `pricing_option_id`. |
| `enum` at `/format_kind` | Sent a non-canonical format kind | Choose a registered canonical kind or use a valid `custom` declaration. |
| `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
| Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | On the AdCP v3 A2A profile, invoke [`get_task_status`](https://adcontextprotocol.org/schemas/v3/protocol/get-task-status-request.json). On MCP, use the advertised AdCP polling task. |
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
"verify:cdn-artifacts-cutover": "node scripts/verify-cdn-artifacts-cutover.mjs",
"typecheck": "tsc --project server/tsconfig.json --noEmit && npm run typecheck:fixed-trace-rollout-tests",
"typecheck:fixed-trace-rollout-tests": "node scripts/typecheck-fixed-trace-rollout-tests.mjs",
"test:schemas": "node tests/schema-validation.test.cjs && node --test tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/identity-absence-coherence.test.cjs tests/execution-requirements.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/lint-schema-enum-drift.test.cjs tests/format-asset-type-parity.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting",
"test:schemas": "node tests/schema-validation.test.cjs && node --test tests/account-ref.test.cjs tests/canonical-account-ref.test.cjs tests/image-bleed.test.cjs tests/sync-plans-reserved-names.test.cjs tests/outcome-target.test.cjs tests/trusted-match-offer-creative-data.test.cjs tests/accessibility-violation-details.test.cjs tests/portfolio-routing-scope.test.cjs tests/catalog-item-availability-updates.test.cjs tests/seller-optimized-package-controls.test.cjs tests/compact-product-lifecycle-storyboards.test.cjs tests/timezone-resolution-storyboards.test.cjs tests/total-budget-redistribution-currency.test.cjs tests/dooh-allocation.test.cjs tests/identity-absence-coherence.test.cjs tests/execution-requirements.test.cjs tests/schema-deprecation-metadata.test.cjs tests/products-only-brief-compatibility.test.cjs tests/async-identity-convergence.test.cjs tests/creative-rotation.test.cjs tests/canonical-forecast-point-parity.test.cjs tests/creative-revisions.test.cjs tests/creative-delivery-contracts.test.cjs tests/tracker-execution-contracts.test.cjs tests/tracker-execution-package-integration.test.cjs tests/metric-identity-coherence.test.cjs tests/viewable-rate-optimization-goal.test.cjs tests/sort-contract-delivery-reporting.test.cjs tests/time-based-views-contract.test.cjs tests/metric-qualifier-parity.test.cjs tests/requested-metrics-contract.test.cjs tests/auto-breakdown-negotiation-contract.test.cjs tests/format-delivery-reporting-contract.test.cjs tests/inventory-delivery-reporting-contract.test.cjs tests/lint-schema-enum-drift.test.cjs tests/format-asset-type-parity.test.cjs tests/synthetic-depiction.test.cjs tests/creative-rendering-authority.test.cjs tests/buyer-reason.test.cjs tests/error-recovery-vectors.test.cjs tests/reporting-status-contract.test.cjs tests/reporting-reconciliation-fixture.test.cjs tests/reporting-core-fixture.test.cjs tests/reporting-native-version-ref-bounds.test.cjs && npm run test:premium-display-formats && npm run test:geo-region-targeting",
"test:performance-feedback": "node --test --test-force-exit --test-timeout=30000 tests/performance-feedback-contract.test.cjs",
"test:dist-schema-version-ids": "node --test --test-force-exit --test-timeout=30000 tests/dist-schema-version-ids.test.cjs",
"test:examples": "node tests/example-validation-simple.test.cjs && npm run test:tmp-context-merge",
Expand Down
23 changes: 18 additions & 5 deletions scripts/mcp-schema-projection.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -813,6 +813,15 @@ function stripPresentationAnnotations(schema) {
return stripped;
}

/** True for `{ required: [...] }` or an `anyOf` of only such clauses. */
function isNamedRejection(not) {
const requiredOnly = value => value && typeof value === 'object' && !Array.isArray(value)
&& Object.keys(value).length === 1 && Array.isArray(value.required);
if (requiredOnly(not)) return true;
return Boolean(not) && typeof not === 'object' && Object.keys(not).length === 1
&& Array.isArray(not.anyOf) && not.anyOf.length > 0 && not.anyOf.every(requiredOnly);
}

function stripModelContextAnnotations(schema) {
const stripped = stripPresentationAnnotations(schema);
walkSchema(stripped, node => {
Expand All @@ -835,11 +844,15 @@ function stripModelContextAnnotations(schema) {
// Exact const values and homogeneous enums already communicate their JSON
// types. Mixed enums retain type because it still narrows the listed values.
if (Object.hasOwn(node, 'const')) delete node.type;
// Closed-object enforcement belongs to the validation profile. The
// declared property list already communicates the prompt shape, while
// retaining `additionalProperties: true` and schema-valued maps preserves
// meaningful extension and dictionary surfaces.
if (node.additionalProperties === false) delete node.additionalProperties;
// Closed-object enforcement belongs to the validation profile; the
// declared property list communicates the prompt shape. Boolean true is
// JSON Schema's default, so omit that redundant spelling as well. Retain
// schema-valued additionalProperties to describe typed dictionary values.
if (typeof node.additionalProperties === 'boolean') delete node.additionalProperties;
// A named rejection (`not` over required names only, beside declared
// properties) is validation, like the bounds omitted above; the validation
// profile keeps it. A bare `not` branch of a union is logic and stays.
if (node.properties && isNamedRejection(node.not)) delete node.not;
for (const keyword of Object.keys(node)) {
if (keyword.startsWith('x-')) delete node[keyword];
}
Expand Down
11 changes: 7 additions & 4 deletions server/src/training-agent/source-schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -76,11 +76,14 @@ function linkedSchemaType(uri: string): unknown {
return linked && typeof linked === 'object' ? (linked as JsonSchema).type : undefined;
}

function keepDefinitionKey(key: string): boolean {
function keepDefinitionKey(key: string, value?: unknown): boolean {
return key !== '$id'
&& key !== '$schema'
&& (key === 'x-adcp-schema-uri' || !key.startsWith('x-'))
&& !definitionAnnotationKeys.has(key);
&& !definitionAnnotationKeys.has(key)
// `additionalProperties: true` is JSON Schema's default and carries no
// information, so referenced definitions omit it from tools/list.
&& !(key === 'additionalProperties' && value === true);
}

/** Build one self-contained schema without duplicating referenced schemas or
Expand Down Expand Up @@ -146,7 +149,7 @@ function bundleSchema(root: JsonSchema): JsonSchema {

const siblings = Object.fromEntries(
Object.entries(record)
.filter(([key]) => key !== '$ref' && (!definitionPath || keepDefinitionKey(key)))
.filter(([key, entry]) => key !== '$ref' && (!definitionPath || keepDefinitionKey(key, entry)))
.map(([key, entry]) => [key, rewrite(entry, definitionPath)]),
);
if (Object.keys(siblings).length === 0) return { $ref: rewrittenRef };
Expand All @@ -157,7 +160,7 @@ function bundleSchema(root: JsonSchema): JsonSchema {

return Object.fromEntries(
Object.entries(record)
.filter(([key]) => !definitionPath || keepDefinitionKey(key))
.filter(([key, entry]) => !definitionPath || keepDefinitionKey(key, entry))
.map(([key, entry]) => [key, rewrite(entry, definitionPath)]),
);
}
Expand Down
Loading
Loading