Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
737b483
refactor(schemas): name five repeated scalar subschemas and $ref them…
KonstantinMirin Nov 2, 2026
a4c25b5
refactor(schemas): name the other repeated scalar concepts and $ref t…
KonstantinMirin Nov 2, 2026
5b491c8
refactor(schemas): name repeated inline enums and $ref them from 164 …
KonstantinMirin Nov 2, 2026
2e157c2
refactor(schemas): reference existing documents from 11 more inline c…
KonstantinMirin Nov 3, 2026
17c0b82
feat(schemas): fail CI on inline copies of named schemas and new unna…
KonstantinMirin Nov 3, 2026
1f9ceb9
fix(schemas): follow named references in tests and the capabilities b…
KonstantinMirin Nov 3, 2026
904760f
test(schemas): check the named document behind four $ref assertions
KonstantinMirin Nov 3, 2026
4397aea
refactor(schemas): give every remaining repeated constraint one defin…
KonstantinMirin Nov 3, 2026
16dfd7e
feat(schemas): fail CI on any repeated constraint, inside a document …
KonstantinMirin Nov 3, 2026
95248f7
test(schemas): resolve named schemas in the budget-too-low details test
KonstantinMirin Nov 3, 2026
3b7d2f9
refactor(schemas): give each concept that shared a constraint its own…
KonstantinMirin Nov 4, 2026
bcc3b2d
fix(schemas): point every timezone at core/iana-timezone.json
KonstantinMirin Nov 4, 2026
dc4ca93
fix(schemas): point every other drifted site at its named schema
KonstantinMirin Nov 4, 2026
2d938f8
feat(schemas): remove held_apart, so a repeated constraint has no opt…
KonstantinMirin Nov 4, 2026
309831a
test(schemas): move the MCP projection bounds for one definition per …
KonstantinMirin Nov 4, 2026
d5f7ad8
fix(schemas): list_products incomplete scope excludes proposals again
KonstantinMirin Nov 5, 2026
ff0eb0e
Merge branch 'main' into schemas/name-repeated-shapes-8525
KonstantinMirin Nov 5, 2026
442ee8e
fix(schemas): every timezone references core/iana-timezone.json
KonstantinMirin Nov 5, 2026
8ab62b9
docs(dr-0036): correction (f) names the timezone minimum as well as t…
KonstantinMirin Nov 5, 2026
54b830d
feat(schemas): plan a 64-character 4.0 limit for IANA timezone identi…
KonstantinMirin Nov 5, 2026
324938e
docs(governance): state DR-0036 as a decision; corrections live in th…
KonstantinMirin Nov 6, 2026
9ccfe4d
Merge branch 'governance/dr-0036-decision-only' into schemas/name-rep…
KonstantinMirin Nov 6, 2026
f8a052e
docs(reference): list the domain, timezone and per-concept bound corr…
KonstantinMirin Nov 6, 2026
849afb6
fix(schemas): a timezone is 1 to 255 characters that resolve in the TZDB
KonstantinMirin Nov 7, 2026
b8dc28f
docs: say branch, schema and response, not arm and shape
KonstantinMirin Nov 7, 2026
b114f6d
Merge the DR-0036 wording fix (#8777)
KonstantinMirin Nov 7, 2026
c949b62
docs(schemas): say branch and notification type, not arm and event shape
KonstantinMirin Nov 7, 2026
8a652a6
Merge origin/main into schemas/name-repeated-shapes-8525
KonstantinMirin Nov 9, 2026
2a53f23
Merge origin/main into schemas/name-repeated-shapes-8525
KonstantinMirin Nov 15, 2026
db9c52c
Merge origin/main into schemas/name-repeated-shapes-8525
KonstantinMirin Nov 15, 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
  •  
  •  
  •  
1 change: 1 addition & 0 deletions .agents/playbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,7 @@ All documentation and examples MUST match JSON schemas in `static/schemas/source
helper stubs, top-level `return`, TypeScript-only syntax in a `typescript`
fence, or a flow the hosted test agent cannot serve). Say so in the prose
right above the fence.
- Before you declare a pattern, an enum, or bounds inline, look in `core/` and `enums/` and `$ref` the named schema, or put a constraint that repeats inside one document in its `definitions`. A value that means something else gets a named schema of its own. `npm run test:schema-named-constraints` fails on an inline copy or a repeat, and nothing opts a site out.
- ID-bearing fields that can cross storyboard step boundaries must carry an `x-entity` annotation — see `docs/contributing/x-entity-annotation.md`. For bulk sweeps use `node scripts/add-x-entity-annotations.mjs` with `scripts/x-entity-field-map.json`.

### Expert Review Scenarios
Expand Down
5 changes: 5 additions & 0 deletions .changeset/app-store-and-asset-source-drift.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": minor
---

Two enums that had drifted now share one definition with their other sites (#8525). `brand.json` property `store` references `enums/app-store.json` and accepts `fire_tv` and `vizio`, as the brand claim requests already did. The `native_in_feed` canonical format's `asset_source` references `enums/asset-source.json` and accepts `publisher_host_recorded`, as every other canonical format already did. Both changes only add accepted values.
5 changes: 5 additions & 0 deletions .changeset/name-repeated-scalar-schemas.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"adcontextprotocol": patch
---

Name repeated scalar subschemas (#8525). The currency code, country code, idempotency key, domain name, and HTTPS URL each move into a titled `core/` document, and the sites that stated them inline now `$ref` that document. Each site keeps its own `description` and other annotations. The same applies to every other scalar constraint that repeats, such as digests, versions, geographic codes, entity identifiers, numeric ranges, and enums: a constraint that repeats across documents moves to `core/` or `enums/`, and one that repeats inside a document moves to that document's `definitions`. A site moves only when the sites mean one concept and state identical constraints. There is no exception list: a site that means something else gets a named schema of its own. Apart from the two enum widenings in the separate changeset, no document's accepted set changes: `npm run test:schema-extraction` resolves every added `$ref` and compares the result with the base document.
29 changes: 29 additions & 0 deletions .changeset/one-definition-per-concept.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
"adcontextprotocol": minor
---

Sites that meant the same thing as a named schema, and stated a different constraint, now reference that schema (#8525). This changes what these sites accept.

**Tighter:**

- 41 timezone sites reference `core/iana-timezone.json`, including every `budget_cap_timezone`, the reporting `timezone` in `reporting_capabilities` and `get_account_financials`, and `supported_timezones`. They reject a value longer than 255 characters, and the 10 that accepted an empty string no longer do. A value must resolve in the implementation's IANA Time Zone Database.
- 10 `governance_context` request fields reference `core/governance-context.json`, so `governance_context` is printable ASCII at every site, as 3.2.8's `core/protocol-envelope.json` published it. This is a correction under DR-0036: it applies the rule that 3.2.8 already published for the concept. 7 of these fields were in 3.2.8 without the rule; the other 3 are new in 3.3.
- 8 `proposal_id` sites, 2 `catalog_ids` lists, and the wholesale feed signal `name` and `description` gain a length limit: 255 characters through `core/signal-name.json` and 2,000 through `core/signal-description.json`. `core/reporting-delivery-offering-id.json` lowers 3 `offering_id` limits from 255 to 128 and adds a pattern.
- `core/media-buy-id.json`, `core/account-id.json`, and `core/creative-evaluation-id.json` state `maxLength: 255`, so every site that references them gains it.
- `core/cancellation-reason.json` and `core/signal-description.json` state `minLength: 1`, so these values can't be empty anywhere. `core/account-request-id.json` states the ID pattern.
- `mraid_versions` in `get_adcp_capabilities` accepts only `2.0` or `3.0`, the values of `enums/mraid-version.json`, instead of any MAJOR.MINOR. An MRAID version is 2.0 or 3.0 at every site, as 3.2.8's `html5` format published `mraid_version`. This is a correction under DR-0036: it applies the rule that 3.2.8 already published for the concept.
- `reporting_profile` and `delivery_config_id` sites gain their named pattern. Webhook `token` sites gain a 4,096-character limit, suggestions gain a 1,000-character limit, and the `request_proposals` rejection `reason` gains a 2,000-character limit.
- Trademark and brand claim `countries` require an uppercase ISO 3166-1 alpha-2 code, and the targeting modification selector `system` requires a postal system from `enums/postal-system.json`.
- `core/domain-name.json` states the 253-character DNS limit, so every domain name site gains it. `upstream_source_domain` also requires a lowercase domain.

**Looser, where the stricter copy rejected a published value:**

- 2 whole-number aspect ratios accept decimals, because `core/format.json` published `1.91:1`.

**Looser, because the named schema drops a rule:**

- `core/iana-timezone.json` drops its character pattern and its `not: {const: inventory_local}`. A timezone is a string of 1 to 255 characters that must resolve in the implementation's IANA Time Zone Database, and no value either rule rejected resolves there. The daypart `timezone` is the only site that accepts `inventory_local`, as a `const` branch beside the IANA identifier.

**Planned for 4.0:**

- `core/iana-timezone.json` plans a 4.0 limit of 64 characters with `x-max-length-4.0: 64`, so every timezone site carries it. The longest IANA timezone identifier is 32 characters. 3.x keeps the `maxLength: 255` that 3.2.8 published.
3 changes: 3 additions & 0 deletions .github/workflows/build-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,9 @@ jobs:
- name: Language-tag schema reference guard
run: npm run test:language-tag-refs

- name: Named-constraints schema guard (no inline copies or unnamed repeats)
run: npm run test:schema-named-constraints

- name: Additive-minor schema guard (no new non-additive changes)
# On pull requests the baseline may only shrink relative to the
# target branch's copy.
Expand Down
9 changes: 7 additions & 2 deletions docs/building/by-layer/L1/security.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2553,15 +2553,20 @@ fields the schema enforces nothing new in 3.x. Each carries the bound as an
annotation instead, `x-max-items-4.0`, `x-max-length-4.0`, or
`x-max-properties-4.0`, which becomes the keyword in 4.0. Through 3.x a producer
**SHOULD** stay within the annotated limit, and a document above it stays
schema-valid. The annotations are registered as a 4.0 tightening in the
schema-valid. A position can carry both, when a 3.x release published a
keyword and 4.0 plans a lower limit: an IANA timezone identifier enforces
`maxLength: 255`, which 3.2.8 published, and annotates `x-max-length-4.0: 64`.
An annotation never sits above the keyword, because that would plan a
loosening. The annotations are registered as a 4.0 tightening in the
[4.0 compatibility checks](/docs/reference/migration/v4-compatibility#capabilities-stay-within-their-structural-bounds).

**Worst case.** With the 4.0 bounds applied, the largest schema-valid
capabilities document is 99,101,211 bytes (about 95 MiB), counting only the
capabilities document is 99,051,419 bytes (about 94 MiB), counting only the
members the schema declares. `scripts/capabilities-structural-bounds.cjs` computes it
and `tests/capabilities-structural-bounds.test.cjs` pins it, so the figure moves
only when a declared member or limit changes. The calculation assumes every declared member is
present, every list and map is full, every string is at its maximum length, a
position with both a keyword and an annotation takes the lower limit, 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),
Expand Down
2 changes: 1 addition & 1 deletion docs/media-buy/advanced-topics/targeting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ Every `daypart_targets` entry uses either `inventory_local` or a concrete IANA t
}
```

`inventory_local` evaluates the window in the seller-assigned local civil time of each inventory unit that can deliver the impression—for example, 9–11am at each screen, venue, broadcast station, or publisher property. It never means the buyer, account, or server timezone. A concrete IANA zone evaluates one civil-time clock across all targeted inventory—for example, 9–11am New York time everywhere. Omitting `timezone` defaults to `inventory_local`. Numeric UTC offsets are invalid because they do not define daylight-saving transitions, and sellers MUST validate concrete identifiers against their supported IANA timezone database. A syntactically valid but unknown identifier is `INVALID_REQUEST`.
`inventory_local` evaluates the window in the seller-assigned local civil time of each inventory unit that can deliver the impression—for example, 9–11am at each screen, venue, broadcast station, or publisher property. It never means the buyer, account, or server timezone. A concrete IANA zone evaluates one civil-time clock across all targeted inventory—for example, 9–11am New York time everywhere. Omitting `timezone` defaults to `inventory_local`. Numeric UTC offsets are invalid because they do not define daylight-saving transitions, and sellers MUST validate concrete identifiers against their supported IANA timezone database. An unknown identifier is `INVALID_REQUEST`.

There is no `user_timezone` or `account_timezone` daypart value. A buyer starting from either preference resolves it to a concrete IANA identifier before sending the request, so later preference changes cannot reinterpret an existing schedule. The daypart delivery clock is independent of `reporting_capabilities.timezone`, which controls report bucketing only.

Expand Down
2 changes: 1 addition & 1 deletion docs/reference/3-3-beta.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,7 @@ Milestone assignment means **candidate for the 3.3 line**, not a commitment to a
| JWS artifacts use the Web Bot Auth key directory ([DR-0026](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0026-jws-artifacts-use-the-wba-key-directory.md)) | Governance contexts, designated-task response signatures, and rights attestations from an origin its trust record lists verify against that origin's Web Bot Auth key directory in 3.3; amends DR-0023. | Merged: [#8299](https://github.com/adcontextprotocol/adcp/pull/8299). |
| Seller revisions advance on every committed change ([DR-0031](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0031-seller-revision-any-origin.md)) | A seller-maintained revision (media-buy and account `revision`, creative `seller_revision`) advances on every committed change, whatever its origin; the `sync_creatives` assignment carve-out is removed. Other resource families are deferred to 3.4. | Merged: [#8159](https://github.com/adcontextprotocol/adcp/pull/8159); recorded in [#8389](https://github.com/adcontextprotocol/adcp/pull/8389). |
| A major-only request is served the oldest supported release ([DR-0034](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0034-major-only-requests-are-served-the-oldest-release.md)) | A request that carries `adcp_major_version` and no `adcp_version` is served the oldest release the seller supports in that major, 3.0 where supported, and the response echoes it. `adcp_major_version` is removed in 4.0 ([DR-0035](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0035-adcp-major-version-removed-in-4-0.md)). | Accepted 2026-10-26; ratified in [#8410](https://github.com/adcontextprotocol/adcp/pull/8410). |
| Schemas are open by default ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)) | 3.3 opens the schemas that were meant to be open; a schema stays closed only for a structural reason, and `commercial_terms` is held closed until 4.0. A minor adds to open schemas and adds nothing to closed ones. Definition pins, purchase rights, and installment selection stay [withdrawn](#withdrawn-after-beta-1), because they add terms to `commercial_terms`. See [Schemas are open by default](/docs/reference/migration/3-2-to-3-3#schemas-are-open-by-default). | Decided at the 2026-11-09 working-group session. The proposal-flow reopening merged in [#8531](https://github.com/adcontextprotocol/adcp/pull/8531), and the CI guard in [#8502](https://github.com/adcontextprotocol/adcp/pull/8502). |
| Schemas are open by default ([DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)) | 3.3 opens the schemas that were meant to be open; a schema stays closed only for a structural reason, and `commercial_terms` is held closed until 4.0. A minor adds to open schemas and adds nothing to closed ones. Definition pins, purchase rights, and installment selection stay [withdrawn](#withdrawn-after-beta-1), because they add terms to `commercial_terms`. See [Schemas are open by default](/docs/reference/migration/3-2-to-3-3#schemas-are-open-by-default). | Decided at the 2026-11-09 working-group session. The proposal-flow reopening merged in [#8531](https://github.com/adcontextprotocol/adcp/pull/8531), the corrections that bound a concept in [#8547](https://github.com/adcontextprotocol/adcp/pull/8547) and [#8536](https://github.com/adcontextprotocol/adcp/pull/8536), and the CI guard in [#8502](https://github.com/adcontextprotocol/adcp/pull/8502). |
| Verifiers bundle the Public Suffix List ([DR-0037](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0037-psl-bundled-not-pinned.md)) | Verifiers compute eTLD+1 with a Public Suffix List bundled with the verifier, never fetched at runtime, and AdCP names no reference snapshot. On the trust-record path, a verifier whose list lacks a newly added PRIVATE suffix fails closed. | Ratified 2026-11-02: [#8702](https://github.com/adcontextprotocol/adcp/pull/8702). |

Four records document surfaces merged for beta.0 and are accepted (decided 2026-10-30): [DR-0027](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0027-mutation-outcome-on-error.md) (`error.mutation_outcome`), [DR-0028](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0028-sales-fixed-rate-specialism.md) (`sales-fixed-rate`), [DR-0029](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0029-delivery-projection-advisory.md) (delivery projection), and [DR-0030](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0030-media-buy-lineage-forward-only.md) (media-buy lineage). `sales-fixed-rate` is promoted from preview to stable in beta.5 ([#8445](https://github.com/adcontextprotocol/adcp/pull/8445)).
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/migration/3-1-to-3-2.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -333,7 +333,7 @@ these tasks' request and response schemas closed, with
`package-control`, and `opportunity-context`.
[DR-0019](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0019-closed-row-schemas-deliberate-class.md)
keeps roots and containers open, so later 3.2 patches reopen them. This is a
correction recorded in
correction under
[DR-0036](https://github.com/adcontextprotocol/adcp/blob/main/governance/decisions/DR-0036-closed-schemas-stay-closed-within-a-major.md)
([#8501](https://github.com/adcontextprotocol/adcp/issues/8501)). Every payload
that was valid stays valid. A field that only the legacy Product defines,
Expand Down
Loading
Loading