Skip to content
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 246 additions & 0 deletions governance/decisions/DR-0039-4x-evolution-contract.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
---
id: DR-0039
title: "4.x evolution contract: additive minors on open schemas, machine-readable deprecation, removal only in a major, and a clock on experiments"
class: normative
status: proposed
date: 2026-11-10
refs: ["#8756", "PR #8704", "PR #8858", "PR #8866", "#8501", "DR-0007", "DR-0009", "DR-0024", "DR-0034", "DR-0035", "DR-0036"]
dissent: "none recorded; comments on RFC #8756 are open until 2026-12-04"
---

## Decision

This record is the evolution contract for AdCP 4.x, from 4.0.0 until 5.0. It
is theme T3 of RFC #8756. Sections 1 to 4 cover stable surfaces, section 5
covers experimental surfaces, and section 6 covers every response.

### 1. The four rules

The rules that PR #8704 put on the versioning page govern every 4.x release,
as they govern 3.x:

1. **A minor only adds.** New fields go on open schemas. Nothing is removed,
renamed, retyped or made required, and no validation rule is tightened.
2. **To replace a field, add the new one and deprecate the old one.** Senders
emit both until the next major.
3. **Removals and breaking changes happen in a major.**
4. **A minor never adds a field to a mutating request if an older seller that
ignores it would commit to something different.** Spend, targeting, caps,
bidding, creative activation, measurement and account identity are
examples, not the full list. Such a field waits for the next major, with
one exception: it may ship in a minor behind a capability that the seller
declares on `get_adcp_capabilities`. A buyer MUST NOT send the field to a
seller that does not declare the capability. A seller that declares it MUST
honor the field, because a declared capability is a commitment ("Features
over versions" on the versioning page).

**The additive-minor check runs from 4.0.0 with an empty baseline.** From
4.0.0 GA, `scripts/lint-additive-minor.cjs` checks every 4.x branch against
the latest 4.x release. Its baseline starts at `4.0.0` with no entries, and so
does the corrections register (DR-0036). Nothing in the 3.x baseline carries
over. In 4.x a baseline entry needs a ratified decision record that names the
change; "pending WG decision" is not a reason. Without one, the change waits
for 5.0. The 4.0 prereleases are not checked against 3.x, because they are the
major.

### 2. Schemas are open by default

DR-0036 (rewritten in #8858, merged) holds in 4.x. A schema is open unless it is
closed for a structural reason, and a schema that stays closed changes only in
a major. In 4.x the structural reasons are a fixed list: the reasons PR #8866
approved for the schemas 3.3 keeps closed, grouped as eight.

| Reason | What closure enforces |
|---|---|
| Key-presence disjointness | The `oneOf` or `anyOf` branches are told apart only by which keys are present, so an open branch would also match a sibling's payload. |
| Signed or digest-bound terms | An extra key would change what a party agreed to. `commercial-terms`, which `terms_digest` binds, is the main case. A must-understand constraint such as `proposal-budget-constraint` is one too. |
| Join key | Consumers join or reconcile on the key set, so a reader that ignored a new key would merge rows that measure different things. |
| Canonical identity | Only the identity members are allowed, so a reference always serializes to the same bytes. |
| JWS envelope | An extra member would be unsigned data that a reader could take as signed. |
| Privacy boundary | The schema enforces a MUST NOT on what a message carries, such as data minimization, or an error shape that must not become an oracle. |
| No key material or markup | An open-ended class of content stays out of a sensitive document: key material, credentials, markup, or free text put in front of an agent. No list of forbidden names could be complete. |
| ID-keyed map | `patternProperties` validates a map's keys. |

PR #8866 states eleven reasons for the 115 locations 3.3 keeps closed. They
map onto the eight as follows. Grouping changes no location's status, so the
WG can split the eight back into the eleven.

| #8866 reason | Locations | Reason here |
|---|---|---|
| oneOf disjointness | 9 | Key-presence disjointness |
| Signed commercial terms | 25 | Signed or digest-bound terms |
| Hard constraint (must-understand) | 1 | Signed or digest-bound terms |
| Closed key set (join key) | 21 | Join key |
| Closed key set (canonical identity) | 2 | Canonical identity |
| Signature envelope | 1 | JWS envelope |
| Closed key set (privacy boundary) | 22 | Privacy boundary |
| Closed key set (no key material or markup) | 18 | No key material or markup |
| Closed key set (credential-free configuration) | 10 | No key material or markup |
| Closed key set (no free text to agents) | 1 | No key material or markup |
| Map keyed by identifier | 5 | ID-keyed map |

- Each closed node names its reason in `x-closed-reason`, and CI fails a closed
node without one. A new reason needs a new decision record.
- Catching a misnamed field is not a reason to close a schema (DR-0036). When
a field must stay forbidden on an open schema, the schema names it in a
**named rejection**: `not: { anyOf: [{ required: ["field"] }] }`.
- A minor may add a named rejection only for a name the schema already
rejected, as when it opens a closed schema. Forbidding a name that was
accepted is a tightening, so it waits for a major.

### 3. Deprecation is machine-readable

Every schema node marked `deprecated: true` carries:

- `x-deprecated-in`, the release that deprecated it, such as `"4.2.0"`; and
- exactly one of these:
- `x-removed-in`, the major that removes it, such as `"5.0.0"`;
- `x-retained`, a string that says why the node survives the next major.

A deprecated enum value or error code has no node of its own, so it carries
the same facts for each value beside `x-deprecated-enum-values`.

The deprecation lint reads these fields, not the description. It fails a
deprecated node that lacks them, an `x-removed-in` or `x-retained` on a node
that isn't deprecated, and a release that still contains a node whose
`x-removed-in` it has reached. Changing a node's disposition is a recorded
decision and can land in any release.

The rule applies from 4.0.0. The 4.0 removal list gives each node deprecated
in 3.x a disposition: removed in 4.0, or `x-retained`.

### 4. Removal and support

**A major may remove anything deprecated in an earlier release, with no
minimum notice period.** Removals happen only in a major, and the point of a
major is to carry out deprecations. A node deprecated in the last minor before
a major may be removed in that major. Rule 3 also lets a major make a breaking
change that no deprecation preceded, such as a tightening. Each one ships with
the breaking-change notice the versioning page requires.

**Implementers are protected by the previous major's support window.** After a
major's GA, the last minor of the previous major stays supported for at least
**12 months** after the successor's GA. For 4.0 that minor is 3.3. The 12
months match the minimum the versioning page already publishes. Supported
means security fixes and corrections in patches of that line, and no new
features. This widens the versioning page, which today promises the previous
major security patches only. The end-of-support date is published on a sunset
page at the successor's GA.

**This replaces the stable deprecation-notice rule.** The minimum 6 months'
notice before a removal no longer applies. The rule and the 12-month window
are already in `versioning.mdx` (#8858, merged). When a deprecated node is
modified, its `x-removed-in` major holds.

### 5. Experimental surfaces have a clock

**An experimental surface graduates to stable or is removed within four
minors of the release that introduced it.** A surface introduced in 4.1
graduates or leaves no later than 4.5.

- The graduation criteria of `docs/reference/experimental-status.mdx` are
unchanged. The clock only adds a deadline.
- Within a major, the existing 6-week notice applies to any breaking change,
including removal at the deadline. In practice, the decision is due at least
6 weeks before the deadline release.
- A major counts as one release toward the clock. Like any major, it may
change or remove an experimental surface without notice.
- A surface that is experimental in 4.0.0, including one carried over from
3.x, starts its clock at 4.0.0. Its deadline is 4.4.
- The WG may extend one surface's clock once, by up to two minors. The
decision is recorded and cites production evidence that is already
accruing.
- Each experimental node records its clock in a field that the lint reads,
as deprecation does.

**Why four.** Graduation needs 45 days in production, a second implementation
or a production buyer, and 30 days with no open breaking issue. SDK support
and the first production deployment tend to land about a minor after a
surface ships. At 6 to 8 weeks a minor, two minors leave less than the 75 days
one round of evidence needs. Three fit one round but leave no room for a
reshape and its 6-week notice. Four leave room for one reshape.
At the published cadence, with minors every 6 to 8 weeks early in a major and
quarterly later, four minors run from about six months to a year. That is
inside the 18-month minimum between majors, so a surface introduced early in
4.x is decided within 4.x.

### 6. Served-release conformance carries into 4.x unchanged

DR-0024 applies to every 4.x release, with no change:

- A response validates against the published schema of the release it echoes
in `adcp_version`, `get_adcp_capabilities` and webhook payloads included.
- Newer shapes are projected or omitted.
- A seller that cannot serve a release that way does not list it.
- Negotiation fields keep their shape across the major.

A 4.x seller that still lists 3.3 serves a 3.3 pin the 3.3 shape. In 4.x, the
negotiation fields are `adcp_version` and `adcp.supported_versions` (DR-0035),
and DR-0034's major-only serving rule does not apply.

## Rationale

Several 3.x minors broke buyers built for the previous release (#8501). The
four rules and an additive-minor check with an empty baseline make the minor
promise mechanical from the first 4.x release. The alternative is a list of
grandfathered exceptions.

Closing a schema turns every later addition into a break (DR-0036). A fixed
list of reasons keeps closure to the places where it is the contract. The
`x-closed-reason` annotation lets reviewers and CI check the same thing.

Prose doesn't scale for deprecation. RFC #8756 counts 169 of 216 deprecated
nodes with no removal decision. "Removed in the next major" (`bid_price`,
`max_bid`) slips past the test that matches "removed in 4.0". With the
dispositions in fields, the removal list is a query.

A minimum notice period ties a major's date to its newest deprecation: the
major either waits, or the deprecation is carried to the next one. What
protects an implementer is time on a supported line. A removal reaches it only
when it moves to the new major, and the support window lets it choose when.
The window covers every removal in the major at once.

3.x shows that experiments without a deadline stay experimental. RFC #8756
counts 183 schemas that are experimental at the root with no graduation clock,
and 3.3 graduates no experimental surface.

DR-0024 is what makes open schemas safe. A newer field reaches only a peer
served the release that defines it. Nothing in 4.x weakens it.

### Alternatives considered

| Alternative | Why not |
|---|---|
| Keep 6 months' notice before a removal | It ties the major's date to its newest deprecation, and it protects no one the support window doesn't already protect. |
| Allow removals in a minor after notice | It breaks rule 3 and the minor promise that the check enforces. |
| Close schemas by default, so validators catch misnamed fields | Every addition becomes a break, which is the 3.x failure. The `undefined_properties` conformance check catches misnamed fields without that cost. |
| Judge each closure's structural reason per PR | Reviewers can't apply "structural" consistently. A fixed list with an annotation is something CI can check. |
| Carry the 3.x additive-minor baseline into 4.x | It grandfathers the exceptions the major exists to clean up. |
| Keep removal targets in prose | They can't be enforced, and they already slip past the test. |
| No experimental clock | That is the 3.x state. |
| Two or three minors | Too short for 45 days in production and 30 days of stability after SDK lag. It would remove surfaces that are about to qualify. |
| Six or more minors | Close to a full major, which is the 3.x state again. |
| A clock in months | Minors are where the architecture committee already reviews experimental status. A count of minors ties the deadline to that review. |

## Implications

- **On ratification**, before `4.0.0-beta.1`:
- `docs/reference/versioning.mdx`: the support window adds corrections to
its security-only promise.
- `docs/reference/experimental-status.mdx`: add the clock.
- Already done: the 6-month deprecation notice is gone from
`versioning.mdx`, `specification-lifecycle.mdx` and
`experimental-status.mdx` (#8858, merged).
- **Tooling for 4.0:**
- `tests/schema-deprecation-metadata.test.cjs` reads the fields, not prose.
- New checks for `x-closed-reason` and the experimental clock.
- The additive-minor baseline and corrections register are reset at 4.0.0
GA.
- **3.x minors and patches don't change.** They never remove. This record
governs the removals that 4.0 makes of 3.x deprecations.
- **Not settled here:**
- Support terms for 3.1.x and 3.2.x at 4.0 GA.
- How `commercial-terms` grows in 4.0. A declared must-understand extension
point is the expected direction (DR-0036).
- The removal list, the GA date, signing, and the JSON Schema dialect, which
RFC #8756 decides by the 2026-12-18 scope freeze.
Loading