Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
378ae53
fix(schemas): fold in #8772's capability-block and container openings
bokelley Nov 9, 2026
5c75d84
fix(schemas): open the 3.3 schemas that were meant to be open
bokelley Nov 9, 2026
0dbc98f
fix(schemas): keep the privacy clamps closed; drop closure claims fro…
bokelley Nov 9, 2026
7495504
fix(lint): flag additions only to schemas that stay closed
bokelley Nov 9, 2026
f5fa9c7
test(lint): cover the open-by-default additive-minor rule
bokelley Nov 9, 2026
6c7806c
fix(schemas): keep the reporting-status and billing-permission clamps…
bokelley Nov 9, 2026
ae1e397
docs: say schemas are open by default; restate the closed ones' reasons
bokelley Nov 9, 2026
9419f49
fix(schemas): keep trust.json and placement-presentation closed
bokelley Nov 9, 2026
f7b944c
docs: count the 100 locations that stay closed
bokelley Nov 9, 2026
219a550
fix(schemas): keep principal results, reporting destinations and hard…
bokelley Nov 9, 2026
06f439d
docs: count the 116 locations that stay closed
bokelley Nov 9, 2026
27d2608
fix(schemas): keep the reporting-status lookup_unavailable branch open
bokelley Nov 9, 2026
3e739ae
docs(security): count the capability blocks 3.3 opens as open positions
bokelley Nov 9, 2026
c8b959a
fix(schemas): name the fields closure used to reject in opened schemas
bokelley Nov 9, 2026
213414d
test: expect opened schemas to accept unknown keys
bokelley Nov 9, 2026
5d6bfa9
fix(schemas): keep key-presence anyOf unions apart by name
bokelley Nov 9, 2026
abff10a
test: finish the open-schema test fallout
bokelley Nov 9, 2026
221b64e
fix(training-agent): keep tools/list within budget and ignore unknown…
bokelley Nov 9, 2026
cd8bc76
fix(schemas): address review on named rejections and key-presence guards
bokelley Nov 10, 2026
9548ed9
docs: call the commercial terms a hold until 4.0; carry #8772's doc h…
bokelley Nov 10, 2026
c01b095
test: flip probes for dropped rejections; add account-ref and bleed g…
bokelley Nov 10, 2026
961dd1b
chore(lint): prune the additive-minor baseline to base 3.2.9
bokelley Nov 10, 2026
23e469b
docs: point the backport to the next 3.2.x patch; drop stale closure …
bokelley Nov 10, 2026
8e8d504
docs: regenerate compliance symbol links on get_products
bokelley Nov 10, 2026
6c689cc
docs: describe the account-ref guard errors, not additionalProperties
bokelley Nov 10, 2026
fa7aefa
fix(schemas): reserve the plan_hash bookkeeping names on sync_plans p…
bokelley Nov 10, 2026
155896f
Merge origin/main into fix/open-closed-schemas-3-3
bokelley Nov 11, 2026
06dc420
docs(3.3): say the commercial terms are held closed until 4.0
bokelley Nov 11, 2026
55ac5a5
chore(lint): describe the commercial terms as held closed until 4.0
bokelley Nov 11, 2026
7d4dd1b
docs(refinement): match the troubleshooting heading to the error it s…
bokelley Nov 11, 2026
0b21f29
Merge origin/main into fix/open-closed-schemas-3-3
bokelley Nov 12, 2026
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
  •  
  •  
  •  
24 changes: 24 additions & 0 deletions .changeset/open-schemas-meant-to-be-open.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
"adcontextprotocol": minor
---

Open the schemas that were meant to be open (working-group decision of 2026-11-09, DR-0036). Closing a schema only breaks validators that hard-code it, so opening one is not a protocol break.

`additionalProperties` goes from `false` to `true` at 747 of the 859 closed locations in the 3.3 source. Nothing else in those schemas changes, and every payload that was valid stays valid. This includes the capability blocks and containers that #8772 opened (daypart windows, the targeting overlay requirement and support containers, and the spot and canonical reporting capabilities), folded in here with thanks to Konstantin Mirin. The `sync_creatives` `assign` operation opens too. Its `operation` const keeps the branches apart, so it doesn't need #8772's named exception. From #8772, boolean `demographics` on the overlay schemas is also deprecated as the 3.2 shorthand for `{ "age": true }`. Senders MUST send the object form, receivers MUST accept `true`, and only support with `gender: true` satisfies a `gender` requirement. 4.0 removes the boolean form.

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

- `oneOf` forms told apart by key presence: `a2ui/bound-value.json` and the `brand.json` document forms.
- Held closed until 4.0, as a hold rather than a structural reason: `commercial-terms`, `product-purchase`, `change-term`, `change-term-constraints`, `sla-window`, `bidding-policy`, and the canonical measurement terms, performance standard, reporting commitment, pricing option and budget allocation.
- Join keys: metric `qualifier` objects and forecast dimensions.
- `canonical-installment-ref` and the JWS response-payload envelope.
- Privacy clamps: the TMP identity and context match requests, `catalog-item-reference-not-found-error`, the per-agent `PERMISSION_DENIED` and `BILLING_NOT_PERMITTED_FOR_AGENT` details, the `get_principal` recognized, unconfigured and failed results and the `sync_principal` failed result, and the error objects of the `get_reporting_status` `lookup_unavailable` failure.
- Credential-free reporting destinations. `proposal-budget-constraint`, the strict peer of `budget-range`, is held until 4.0 with the commercial terms.
- No key material or markup: `trust.json`, on the signature-verification fetch path, and the declarative `placement-presentation` frame.
- Maps keyed by identifiers (`patternProperties`).

Where closure also rejected a specific field the protocol defines elsewhere, the opened schema names it in `not: { anyOf: [{ required: [...] }] }`, as #8531 did for `canonical-product`. For example, `trackers` and `landing_page_url` stay `assign`-only, hold entries carry no `expires_at`, and delivery-ready webhooks carry no access token. Each node with a named rejection says in its description what it rejects and why, since generated types can't express `not`.

The additive-minor check now flags an added property only where the schema stays closed. It still fails on removals, renames, retypes, removed enum values, tightened bounds, new required names, and closing an open schema. The closed-anywhere-in-the-major rule and the reopening corrections are gone, and the baseline keeps 4 entries, each with its resolution.

**Generated types change.** A generator that reads `additionalProperties` now treats the opened objects as open: json-schema-to-typescript gives them an index signature, and Pydantic models stop forbidding extra fields. A strict validator built from the 3.2 schemas still rejects 3.3 fields on these objects, so send a 3.3 field only to a 3.3 peer. The next 3.2.x patch (#8864) opens the same locations that 3.2 has, all but one: it keeps `get-reporting-status-response.json#/oneOf/1/oneOf/0` closed, as 3.2 published it.
6 changes: 3 additions & 3 deletions .changeset/pre/compose-protocol-envelope-on-task-responses.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
Every task response schema and async status payload now composes `core/protocol-envelope.json` through its root `allOf`, as the envelope's notes already require. On MCP and REST the envelope fields (`status`, `task_id`, `context_id`, `context`, `message`, `timestamp`, `replayed`, `adcp_error`, `push_notification_config`, `governance_context`) are siblings of the body fields at the response root, but 47 of the 124 tool response and async status schemas did not compose the envelope, and 18 closed roots and `oneOf`/`anyOf` branches rejected envelope fields outright, because draft-07 `additionalProperties` does not see properties declared through `allOf`. Generated SDK types therefore could not represent a conforming response.

- `core/protocol-envelope.json` composes `core/version-envelope.json`, so `adcp_version` and `adcp_major_version` are envelope fields on every response, stamped by the server framework rather than carried as task data. Request schemas keep composing the version envelope directly; response schemas no longer do.
- Every response root and status branch is open, as DR-0019 keeps response roots, so the envelope's fields validate where the envelope declares them. The 18 that were closed are reopened: the 3.2 proposal-flow response roots and branches (DR-0036 correction (a)), the `list_collections`, `list_proposals`, `get_media_buy_issue` and `report_media_buy_issue` responses, which are new in 3.3, and the `get_reporting_status` failure branches, which are experimental. Closed value objects and rows inside response bodies stay closed. No build step adds the envelope: source and published schemas agree.
- Every response root and status branch is open, as DR-0019 keeps response roots, so the envelope's fields validate where the envelope declares them. The 18 that were closed are reopened: the 3.2 proposal-flow response roots and branches (reopened earlier in 3.3), the `list_collections`, `list_proposals`, `get_media_buy_issue` and `report_media_buy_issue` responses, which are new in 3.3, and the `get_reporting_status` failure branches, which are experimental. Closed value objects and rows inside response bodies stay closed. No build step adds the envelope: source and published schemas agree.
- A local declaration of an envelope field is kept only where it narrows: a branch's `status` const or enum, a `const` pin such as the fixed `message` and `adcp_error` of an unavailable `get_reporting_status` lookup, and `context` as a `$ref` to `core/context.json`. The 66 other local copies (`task_id` ×23, `message` ×21, `replayed` ×11, the `get_reporting_status` failure branches' `adcp_version`, `adcp_major_version`, `context_id`, `timestamp` and `adcp_error`, `governance_context` on `check_governance`, and `status` on `get_task_status`) are removed, so the envelope's declarations govern. The untrusted-input guidance on the async `message` copies moves to `core/task-message.json`. The root `status` enums on `decline_proposals`, `request_proposals` and `refine_proposals` are removed; their branch consts discriminate.
- The compact proposal-flow responses no longer pin `replayed` to `true` (12 locations); the envelope's boolean governs, so a response accepts `replayed: false`.
- A task-level `message` has one bound of 2,000 characters, in one definition: `core/task-message.json` (`type: string`, `maxLength: 2000`, untrusted input to the receiver). The envelope, the MCP webhook payload and the response wrapper refer to it, so the bound does not depend on the delivery path. The 23 response nodes that capped `message` at 2,000 themselves no longer restate it. A seller whose text is longer MUST truncate it rather than fail the task. 3.2.7's envelope, webhook payload and wrapper declared no bound; DR-0036 records the change as correction (d), at the 2,000 that 3.2.7 published on the compact and submitted responses. A `const` pin on `message`, such as the fixed text of an unavailable `get_reporting_status` lookup, is kept. `core/error.json`, `core/warning.json` and messages inside task bodies keep their own bounds.
- `task_id` has one definition, `core/task-id.json` (`type: string`, `minLength: 1`), that every `task_id` declaration refers to: the envelope, `tasks/get` and `get_task_status` requests and responses, the task list responses and filters, the MCP webhook payload and the compliance controller (which keeps its own `maxLength: 128`). An empty `task_id` identifies no task, so it is rejected; 3.2.7 already published `minLength: 1` on `core/compact-task-submitted.json`. DR-0036 records this as correction (c). A submitted response requires `task_id` through `core/task-submitted.json` (`status: submitted` and a required `task_id`), which every submitted response body and branch composes through `allOf`, so none restates the rule; generated types see the requirement. Likewise every working body composes `core/task-working.json` (`status: working`) and every input-required body composes `core/task-input-required.json` (`status: input-required`), so an async status payload accepts only its own status.
- A task-level `message` has one bound of 2,000 characters, in one definition: `core/task-message.json` (`type: string`, `maxLength: 2000`, untrusted input to the receiver). The envelope, the MCP webhook payload and the response wrapper refer to it, so the bound does not depend on the delivery path. The 23 response nodes that capped `message` at 2,000 themselves no longer restate it. A seller whose text is longer MUST truncate it rather than fail the task. 3.2.7's envelope, webhook payload and wrapper declared no bound; DR-0036 records the change as a correction, at the 2,000 that 3.2.7 published on the compact and submitted responses. A `const` pin on `message`, such as the fixed text of an unavailable `get_reporting_status` lookup, is kept. `core/error.json`, `core/warning.json` and messages inside task bodies keep their own bounds.
- `task_id` has one definition, `core/task-id.json` (`type: string`, `minLength: 1`), that every `task_id` declaration refers to: the envelope, `tasks/get` and `get_task_status` requests and responses, the task list responses and filters, the MCP webhook payload and the compliance controller (which keeps its own `maxLength: 128`). An empty `task_id` identifies no task, so it is rejected; 3.2.7 already published `minLength: 1` on `core/compact-task-submitted.json`. DR-0036 records this as a correction. A submitted response requires `task_id` through `core/task-submitted.json` (`status: submitted` and a required `task_id`), which every submitted response body and branch composes through `allOf`, so none restates the rule; generated types see the requirement. Likewise every working body composes `core/task-working.json` (`status: working`) and every input-required body composes `core/task-input-required.json` (`status: input-required`), so an async status payload accepts only its own status.
- `core/protocol-envelope.json` states that an absent `replayed` means `false` and that a response may carry `replayed: false`; `replayed: true` appears only on a replay.
- Async status payloads and the governance responses now require `status`, which the envelope already made required on every task response. Webhook `result` examples carry the task's `status`.

Expand Down
2 changes: 1 addition & 1 deletion .changeset/pre/reopen-proposal-flow-schemas.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"adcontextprotocol": patch
---

Reopen the 3.2 proposal-flow schemas that were closed against DR-0019, as correction (a) recorded in DR-0036.
Reopen the 3.2 proposal-flow schemas that were closed against DR-0019. They were the first 3.2 schemas 3.3 opened; under the WG decision of 2026-11-09 (DR-0036), 3.3 then opened every schema that was meant to be open.

3.2 published the proposal-flow task roots and containers with `additionalProperties: false`. DR-0019 keeps request roots, response roots, and container objects open. These schemas now set `additionalProperties: true` at the listed locations:

Expand Down
2 changes: 1 addition & 1 deletion .changeset/pre/seller-offers-against-accepted-buys.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ The buyer accepts with `accept_proposal`, declines with `decline_proposals`, or

Seller-held change terms (pre-agreed seller changes inside `commercial_terms.change_terms[]`) are not part of 3.3: `commercial_terms` and `change-term.json` stay closed for the whole 3.x major, so the design is recorded for 4.0 as the `seller_held_change_terms_required_in_4_0` check in the 4.0 compatibility registry and in a "Planned for 4.0" note in the proposal-negotiation guide (#8087). In 3.3 every seller-initiated change to a signed buy is an offer.

Compatibility: sellers MUST NOT send offers or `proposal.offered` notifications to callers served below AdCP 3.3, because `proposal_initiator` is a 3.3 field on a schema reopened in 3.3, and 3.3 fields on reopened schemas go only to 3.3 peers (DR-0036); a caller with no declared pin is treated as below 3.3.
Compatibility: sellers MUST NOT send offers or `proposal.offered` notifications to callers served below AdCP 3.3, because `proposal_initiator` is a 3.3 field on a schema reopened in 3.3, and a seller shapes each response to the caller's served release (DR-0024); a caller with no declared pin is treated as below 3.3.
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"adcontextprotocol": minor
---

Withdraw definition pins, purchase rights, and installment selection from 3.3 and plan them for 4.0 (adcp#8501). All three add terms to `commercial_terms`. The `commercial-terms` schema is closed on purpose: a buyer must not be bound by terms it cannot read, and `terms_digest` signs exactly those terms. If the object were open, a 3.2 buyer could accept a 3.3 term it silently ignored, and a minor release never changes a closed schema (DR-0036). 4.0 gives `commercial_terms` a declared extension point with must-understand, and the three features come back through it.
Withdraw definition pins, purchase rights, and installment selection from 3.3 and plan them for 4.0 (adcp#8501). All three add terms to `commercial_terms`. The `commercial-terms` schema is held closed until 4.0 (DR-0036). 4.0 gives `commercial_terms` a declared extension point with must-understand, and the three features come back through it.

**All three shipped in `3.3.0-beta.1` and are removed after it.** This is a beta-to-beta change, not a change to a stable release. Both betas are immutable, so a seller or SDK built from a beta bundle has the surfaces below to remove. The two experimental features also leave `experimental_features`: a seller stops listing `media_buy.purchase_rights` and `media_buy.installment_selection`.

Expand Down
7 changes: 4 additions & 3 deletions docs/building/by-layer/L1/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2565,9 +2565,10 @@ present, every list and map is full, every string is at its maximum length, a
union takes its widest branch, free text takes four bytes per character, and
patterned or formatted strings one. The largest blocks are `media_buy` (34 MiB),
`creative` (27 MiB), `adcp` (12 MiB), `governance` (6 MiB), `account` (5 MiB),
and `measurement` (4 MiB). Objects that admit undeclared members, such as `ext`
and context, are open: the schema cannot bound what a producer adds there, and
108 positions in the response are open in this sense.
and `measurement` (4 MiB). Objects that admit undeclared members, such as `ext`,
context, and the capability blocks 3.3 opens, are open: the schema cannot bound
what a producer adds there, and 190 positions in the response are open in this
sense.

The multipliers behind that figure are nested object lists inside shared
schemas: a brand reference (`brand-ref`, up to 111 KiB each, most of it
Expand Down
2 changes: 1 addition & 1 deletion docs/governance/campaign/specification.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -929,7 +929,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
Loading
Loading