[bokelley]

Revised against DR-0036 (#8501) and ready for WG consent. First split out of #8410 and parked at WG Session C pending #8501.

What changed in the revision

#8501 settled on DR-0036: a minor adds only to open schemas, closed schemas change only by a recorded correction, and the 3.2 proposal flow is reopened as correction (a). Under that rule an older peer accepts a newer field and silently ignores it, so these records now target the silent-ignore hazard rather than rejection.

• DR-0032 (SDKs negotiate and translate):
  • Newer fields go only to peers that negotiated them.
  • Reads drop the field and report it.
  • Mutations refuse when the lost field would change the commitment: spend, targeting, caps, bidding, creative activation, measurement or account identity.
  • Moves follow DR-0033 pathway statements; up-conversion never removes.
  • Closed and digest-bound objects (commercial-terms) are never reshaped; the resource is refused with VERSION_UNSUPPORTED instead.
  • The 3.2 account-key change, which DR-0036 records as staying until 4.0, reduces one-to-one by default, with explicit migration on seller upgrade.
• DR-0033 (every minor-release change states its pathway back): the forms are now ignorable, gated, moves or a DR-0036 correction. Additions to closed schemas and identity changes are not allowed in a minor at all. It applies to 3.x now and to 4.x from 4.1.
• LADON.md and the constitution invariant enforce the new forms. A field labeled "ignorable" whose loss would change the commitment is high.

Related

• Conformance vectors (feat(compliance): add cross-version translation test vectors #8433): now one file per pair. 3.3-3.2.json covers settled surfaces and is provisional until 3.3 GA.
• Reference implementations:
  • @adcp/sdk: feat: negotiate the AdCP release and translate between releases (client and server) adcp-client#3372 and Training Agent Storyboards: signed_requests 28-vector failure on main since #3351 (PostgresReplayStore swap) #3376.
  • Python: feat(compat): negotiate and translate AdCP minor versions adcp-client-python#1559.
  • Go and Java: still to come (Add Property Governance Protocol for AdCP 3.0 #588, docs: Add comprehensive standard formats documentation #47).

Proposed for consent alongside the 3.3 baseline disposition, with objections by Fri 2026-11-13. This touches governance/, LADON.md and the constitution, so a human merges it.

🤖 Generated with Claude Code

[bokelley]

WG decision brief (Session D, 2026-11-02)

What still needs translation. I counted with node scripts/lint-additive-minor.cjs --history and the baseline at scripts/lint-additive-minor-baseline.json. I classified request, response and shared schemas by file name, so treat that split as approximate.

Hop	Non-additive	Mix
3.0 → 3.1 (shipped)	79	30 required-added, 27 property-added-to-closed, 10 removed, 7 bounds, 3 enum, 2 other
3.1 → 3.2 (shipped)	70	46 property-added-to-closed, 15 bounds, 7 enum, 2 required-added
3.2 → 3.3 (recorded in baseline)	70	69 property-added-to-closed, 1 enum removal

• Of the 70 for 3.3, 12 are 3.1.0 closures recorded as released (11 geo_postal_areas keys and identity.brand_json_url). They stay until 4.0.
• The other 58 are "pending WG decision": 14 on request schemas, 11 on response schemas and 33 on shared schemas. No corrections are recorded yet.
• Resolving each by a DR-0036 route (move to an open parent, record a correction, or revert) leaves 3.2 → 3.3 with nothing structural to translate.
• The 149 findings across 3.0 → 3.1 → 3.2 are frozen. DR-0036 and build(schemas): fail CI when a minor release makes a non-additive schema change #8502 stop the count growing, and DR-0034 serves 3.0 shapes to major-only requests.
• What doesn't go away: a new field on an open schema is silently ignored by an older seller. That is harmless on a hint and wrong on a mutation, such as a cap, an exclusion or lineage_reason.

1. DR-0032 (SDK translation): ratify a narrowed rule, drop it, or defer it?
Recommend ratifying it, narrowed to this rule:

• An SDK negotiates the highest release both sides support, per counterpart and per call. It validates each message against the schema of the release it is exchanged in.
• It does not translate 3.3 against 3.2. It never sends a field newer than the counterpart's served release (x-added-in already marks 3.3 and 3.2 fields) unless dropping it cannot change what the counterpart commits to. Otherwise it refuses with a typed error before sending.
• Structural conversion is limited to a closed list of the shipped 3.0 → 3.1 → 3.2 moves, which cannot grow in 3.x.
• Account-key reduction narrows to the 3.2 → 3.1 seam. spec(accounts): brand identity is the domain, and an account is its account_id #8474 stops 3.3 treating countries, currency, timezone and operator_unit as identity. After a version gap, address accounts by account_id.

2. DR-0033 (downgrade path for every minor change): ratify narrowed, drop, or defer?
Recommend ratifying it narrowed to mutating requests, and dropping the rest.

• DR-0036 and the lint already prove the structural half in CI. "Moves" and "identity-bearing" are not allowed within a major, because a rename is a removal plus an add.
• What a reviewer still has to state: for each new field on a mutating request, whether an older seller ignoring it changes what the seller commits to (droppable or refused).
• Replace the LADON.md mandatory high for every minor change with that one check. Drop the new constitution invariant, or cut it to one line.

3. #8433 (translation vectors): what happens to it?
Recommend keeping it open, rescoped, and not merging it before Session D.

• Keep the shipped-move vectors: bid_amount, assignments, status alias, delivery currency, and the chain to 3.0.
• Keep the account-reduction cases, labelled as the 3.2 → 3.1 seam.
• Keep the refusal vectors, and add 3.3 → 3.2 refusals for mutating fields now in the baseline: lineage_reason, predecessor_media_buy_id, include_collections, and assignment landing_page_url and trackers.
• Drop the three read-drops cases. Ignoring unknown fields is validator behaviour, not translation.
• Move status from proposed to ratified when Q1 and Q2 land.

[bokelley]

Consent round (async; the Nov 2 session is cancelled): objections by Fri 2026-11-06. Proceeding as the Session D brief recommends, @KonstantinMirin please weigh in:

1. DR-0032, ratified in narrowed form:
   • SDKs negotiate per counterpart and validate against the release exchanged.
   • No 3.3 → 3.2 translation. An SDK never sends a field newer than the counterpart's served release unless dropping it can't change what the counterpart commits to; otherwise it refuses with a typed error.
   • Structural conversion is limited to the closed list of shipped 3.0 → 3.1 → 3.2 moves.
   • Account-key reduction applies only at the 3.2 → 3.1 seam.
2. DR-0033, ratified narrowed to mutating requests: a reviewer states, for each new field on a mutating request, whether an older seller ignoring it changes what it commits to. That replaces the blanket high in LADON.md. The constitution invariant is dropped, or cut to one line.
3. feat(compliance): add cross-version translation test vectors #8433, rescoped: keep the shipped-move, account-reduction (3.2 → 3.1) and refusal vectors, and add 3.3 → 3.2 refusals for lineage_reason, predecessor_media_buy_id, include_collections and assignment landing_page_url / trackers. Drop the read-drop cases.

An objection by Friday brings it to the next live session, Mon 2026-11-09.

[aao-secretariat]

Ladon is not auto-reviewing this PR because it modifies the review system itself (LADON.md). A human reviewer should review and merge this PR; Ladon resumes on subsequent PRs once these changes land on main.

[KonstantinMirin]

Hi Brian,

Thanks for putting the brief together. The counts are really useful, and I think the narrowing goes in the right direction. I'd still like to raise an objection on all three items, because I think we can go a step further and make this simpler. You've seen far more of how this plays out in practice than I have, so please tell me if I'm missing something.

My main thought is that a standard defines what goes on the wire between two parties, and how a library gets there probably isn't part of it. So I don't think the standard needs to say anything about SDKs. Either it defines translation between versions or it doesn't, and I believe it shouldn't.

I'd love for version-to-version to come down to a few simple rules:

1. A minor only adds. New fields go on open schemas. Nothing is removed, renamed, retyped or made required, and closed schemas stay closed until the next major. DR-0036 and the additive-minor check already give us this.
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.

If we hold to those, I think most of what these records handle goes away:

• DR-0032: I'd suggest withdrawing it. What an SDK does for its users (negotiating, converting, refusing) feels like that SDK's product decision, and it can live in the SDK's documentation. The shipped 3.0 → 3.1 → 3.2 moves are already described in the migration guides, and SDKs that handle them can keep doing so.
• DR-0033: same suggestion. If a minor only adds, there's no downgrade path to state, and the check already proves the structural part in CI. The LADON.md rule and the constitution invariant could go with it.
• feat(compliance): add cross-version translation test vectors #8433: I'd keep the negotiation vectors, since negotiation is on the wire, and move the conversion, refusal and account-reduction vectors to the SDK repos that want them. One small thing I noticed: the brief lists include_collections as a mutating refusal, while feat(compliance): add cross-version translation test vectors #8433 lists it as a read drop, and it sits on get_products and list_products. I think that shows how hard the per-field classification is to keep straight.

The hazard you describe is real: an older seller silently ignores a new field on an open schema, which is wrong for something like a cap. I just don't think it needs a rule about SDKs. A seller publishes supported_versions and echoes adcp_version on every response, and x-added-in says which release a field belongs to, so a buyer can already tell before sending whether the seller knows the field. What it does with that can be up to the buyer. And a field that must never be ignored probably shouldn't be added in a minor at all, so it would wait for the major.

Could we talk this through at the Nov 9 session? Happy to go through it there.

[KonstantinMirin]

Hi Brian, I've put the three rules up as a docs-only PR so we have something concrete to look at on Nov 9: #8704. It doesn't touch anything proposed here, and it notes that the shipped 3.0 → 3.1 → 3.2 moves stay as history until 4.0. Some entries in the 3.3 exceptions table sit awkwardly with rule 3, so those are worth talking through as well.

[bokelley]

@KonstantinMirin: you've convinced me. The standard defines the wire, and how a library gets there isn't part of it. I'd like to adopt #8704 and withdraw DR-0032 and DR-0033 as normative records.

What we adopt. The three rules in #8704, for the rest of 3.x and for all of 4.x:

1. A minor only adds, and only to open schemas.
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.

One rule I'd add, in your words. You wrote that "a field that must never be ignored probably shouldn't be added in a minor at all." I'd make that the fourth rule:

4. A minor never adds a field to a mutating request if an older seller ignoring it would change what the seller commits to: spend, targeting, caps, bidding, creative activation, measurement or account identity. A field like that waits for the next major, or goes behind a capability the seller has to declare first.

That keeps the one hazard the brief was really about, an older seller silently ignoring a cap, as a rule about what goes on the wire. It isn't a rule about SDKs. In LADON.md, the blanket high on every minor change becomes this single check, and the constitution invariant goes.

What stays as it is. Negotiation, supported_versions, the adcp_version echo and served-release validation (DR-0024) are wire behaviour, so they stay. So does serving major-only requests the oldest release (DR-0034), and so does x-added-in.

What moves out. What an SDK does about a version gap (converting, refusing, reducing account keys) becomes that SDK's documented behaviour. For #8433, I agree with your split: negotiation vectors stay here, and the conversion, refusal and account-reduction vectors move to the SDK repos that want them. You were right about include_collections. The per-field classification was hard to keep straight, and the field has now left get_products anyway (#8758).

Order. We ratify DR-0036 on Monday. Then #8704 merges (Ladon is holding it until DR-0036 is ratified), and I close #8519 with a pointer here. Your point about the 3.3 exceptions table sitting awkwardly with rule 3 is worth the room's time on Monday. The #8501 withdrawals should already have removed most of that tension.

Thanks for pushing on this. It's simpler, and it's the rule 4.0 should be built on (#8756).

🤖 Generated with Claude Code

[KonstantinMirin]

Thanks Brian, I'm glad we landed here. Yes to rule 4, and I'll add it to #8704. One small suggestion: I'd treat the list (spend, targeting, caps…) as examples rather than as the rule's scope, so a field outside the list that still changes the commitment is covered too. The capability route is the same as DR-0036's named exception: the seller declares the capability, and buyers MUST NOT send the field otherwise.

[bokelley]

Closing without merging. The working-group session on Mon 2026-11-09 confirmed what this thread agreed on Nov 6: DR-0032 and DR-0033 are withdrawn as normative records. @KonstantinMirin, thanks for pushing on this.

What replaces them. The four rules at the top of the versioning page, from #8704:

1. A minor only adds.
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. Such a field waits for the next major, or ships behind a capability the seller declares first.

What stays. Negotiation, supported_versions, the adcp_version echo, served-release validation (DR-0024), serving major-only requests the oldest release (DR-0034), and x-added-in are all wire behavior, and all are unchanged.

What moves out. What an SDK does about a version gap (converting, refusing, reducing account keys) is that SDK's documented behavior. For #8433, the negotiation vectors stay in this repo. The conversion, refusal and account-reduction vectors move to the SDK repos that want them.

DR-0036 changed too. This PR was revised against DR-0036's draft rule that a closed schema stays closed for the whole major. The same session reversed that rule:

• Schemas are open within a major.
• A schema is closed only for a structural reason.
• 3.x schemas closed without one are opened in 3.3 and a 3.2.x patch.

See #8858.

The IDs. #8858 adds short DR-0032 and DR-0033 records marked superseded, pointing at the versioning rules. That keeps the IDs reserved and lets existing citations resolve. The proposed text stays here for reference. The LADON.md checks and the constitution invariant proposed here are not adopted.