Repository navigation
Description
The problem
We say a minor release only adds things, so a buyer built for 3.0 keeps working against a 3.2 seller. In practice it sometimes doesn't.
Some of our schemas are published as closed. A closed schema tells a validator to reject any field it doesn't recognize. When a later minor adds a field to a closed schema, a buyer that validates against its own release rejects the newer response. That's a breaking change, even though the field is optional.
This has happened in every minor so far. Two examples:
- The brand reference was closed in 3.0. It gained
brand_kit_overridein 3.1 andcountriesin 3.2. - The account reference (the brand + operator form) was closed in 3.0. It gained
currency,timezoneandoperator_unitin 3.2.
A check that compares each release with the previous one (#8502) counts the changes that aren't additive. Experimental features are left out, because they're allowed to change:
| From → to | Changes that aren't additive |
|---|---|
| 3.0 → 3.1 | 79 |
| 3.1 → 3.2 | 70 |
| 3.2 → 3.3 beta | 41 |
Why it keeps happening: two rules that disagree
- DR-0009 says schemas are open by default, so that minors can add optional fields "without invalidating existing traffic". The versioning docs add that readers must ignore unknown fields.
- DR-0019 (from Policy: closed (additionalProperties: false) row schemas vs DR-0009's open-by-default — decide once #7224) allows closed schemas for certain kinds of objects. It also says adding an optional field to a closed schema is a minor change, while noting that older validators will reject it.
Each rule makes sense on its own. Together they allow minor releases that break older buyers, and implementers can't tell which rule to rely on. The cost shows up elsewhere. Sellers have to shape responses to each buyer's release (DR-0024). Requests that only say "version 3" now get the oldest release (DR-0034). And DR-0032 proposes translation code in every SDK.
Proposal
- One rule: a minor release never breaks a buyer that validates against its own release. A closed schema stays as it is until the next major. New fields go into an open schema, a new schema, or the next major.
- Update DR-0019 to match. Its idea of closed schemas can stay; closed just means frozen within a major.
- Check it in CI (build(schemas): fail CI when a minor release makes a non-additive schema change #8502). The changes already made are listed in a baseline that can only shrink, so nothing fails today and nothing new slips in.
- Before 3.3 is final, decide what to do with each field 3.3 adds to a closed schema: move it, send it only to buyers on 3.3, or leave it for 4.0.
I'm happy to do the follow-up work.
Activity
bokelley commentedon Oct 26, 2026
WG Session C (2026-10-26) accepted the problem. Adding a property to a schema published with
additionalProperties: falsebreaks older strict validators, exactly as removing a field does.DR-0032 and DR-0033 are parked until this is settled.
KonstantinMirin commentedon Oct 26, 2026
Thanks for taking this up at Session C. Here's the triage I owe for the 3.3 additions to closed schemas.
The rule I applied: a minor release only adds, and it never adds to a closed schema (
additionalProperties: false). A closed schema stays exactly as it is until 4.0. I didn't make exceptions for fields sent only to 3.3 peers, or for experimental fields, because either one would still break a strict 3.2 validator.For each of the 57 new fields on closed schemas there are two outcomes. Either the field moves to the nearest open object that contains its closed parent, keeping its meaning, or it waits for 4.0. 15 move and 42 wait. The
evaluatorvalue removed from thex-entityregistry comes back.Most of the 42 share one cause. In 3.2,
list_products,request_proposals,refine_proposals,buy_products,accept_proposal,decline_proposalsandcontrol_media_buywere published closed from the request or response object down. So proposals, purchases and commercial terms have no open place to grow in 3.x. DR-0019 asks for roots and containers to stay open, so I'd treat that as something to reopen in 4.0, together with declared extension points, rather than as anyone's mistake today.daypart_windowson targeting, with the granularity onoverlay_supportandget_productspackage_forecasts[]andpackage_forecast_results[]onget_productsreporting_capabilitiesget_productsrequestexpected_confirmation_at, the creative start policy,metric_id, assignment landing page and trackers, webhooksigning_profilelist_productsversion echo,product_ids_exclusiveThe full per-field list, with the open object each field moves to and the reason for each deferral, is in this gist.
Follow-ups I'll open:
identityblock was closed in 3.0.0, opened in 3.0.5, and gainedbrand_json_urlin 3.1.0.evaluator, remove the deferred fields with the capability flags of the features that wait, and one PR per moved feature, agreed with its owner first.@bokelley, I know this costs 3.3 features the group already agreed on, and I'm sorry to bring it this late. Could you check the list before we cut 3.3.0-beta.1? Six features wait for 4.0, and the moves change the wire form of #8025 and #8468, so their owners should see it too. I'm happy to walk through any of it.
feat(schema): selection-dependent price_adjustments on fixed-price pr…
docs(governance): ratify DR-0034; split DR-0032/0033 out to #8519
feat(schema): selection-dependent price_adjustments on fixed-price pr…
docs(governance): ratify DR-0034 (major-only requests serve the oldes…
bokelley commentedon Oct 27, 2026
Thanks, Konstantin. This is careful work. I'd accept the analysis method, the 15 moves, the narrowings, the
evaluatorrestore and the check fix (closed anywhere in the major) as written. Theidentitycase shows why the fix matters.Before we accept the 42 deferrals, I'd like to question their main cause rather than live with it until 4.0. Most of them, and all six features that slip (holds, installment selection, purchase rights, definition pins, the
list_productsversion echo,product_ids_exclusive), come from one thing: the 3.2 proposal flow was published closed from the root down. As far as I can find, nobody decided that, and it contradicts our own records.What the records say:
additionalProperties: falseonly on row schemas: join-key objects, or row envelopes that keep anextescape hatch. It also says outright that "response roots, capability blocks, and container objects stay open."What 3.2 shipped:
extrequest_proposalsrequest (root)request_proposalsresponse (root)list_productsrequest (root)buy_productsrequest (root)canonical-proposal(container)commercial-termscanonical-productThe roots and containers are closed, which DR-0019 says they must not be. Several of them also lack the
extslot DR-0019 requires of a closed envelope. None carries a note explaining why. I read this as a 3.2 defect, not a deliberate design.One exception is deliberate in substance:
commercial-terms. A buyer must not be bound by terms it can't read, and those terms are whatterms_digestsigns. If the object were open, a 3.2 buyer could accept a 3.3 term (rights, pins, installments) it silently ignored. Exhaustive keys there fit DR-0019's join-key class, and I'd keep it closed.Proposal:
canonical-proposal,canonical-product,product-discovery-criteria,proposal-refinement,package-control), and keepcommercial-termsclosed. Loosening is non-breaking under DR-0019: anything valid before stays valid. These tasks are new in 3.2, so the strict validators that exist for them are almost all the SDKs, and we'll patch those.supported_versions(the 3.2 grader blocks otherwise), so negotiation is reliable here. An un-updated strict 3.2.0–3.2.7 validator therefore never sees a 3.3 field from a conformant seller.purchases[]) are offered only to buyers that negotiated 3.3. A seller never serves a pre-3.3 peer a proposal whosecommercial-termsuses them. It returnsVERSION_UNSUPPORTEDfor that proposal instead of stripping terms, which would also breakterms_digest. This keeps the reason the object is closed: nobody receives terms they can't read.What this costs:
What it buys:
If the group prefers the strict rule without this exception, I'll take your list as is. Either way, can we settle it at the next session, or async this week, so 3.3.0-beta.1 isn't blocked? I'm happy to write the errata PR and the #8502 changes if we go this way.
KonstantinMirin commentedon Oct 27, 2026
Thanks, Brian. You're right about the cause. DR-0019 says roots and containers stay open, and nobody decided to close the 3.2 proposal flow. #8518 shows the same closure even blocks the version echo the versioning page requires. So I'd treat it as a defect to correct, not a rule to live with.
Where I land on your four steps:
commercial-termsin 3.3: no. It's the one object closed on purpose, for the reason you gave: a buyer must not be bound by terms it can't read. Adding fields to it in a minor, and relying on negotiation to keep that safe, brings back the exception we decided against on Monday, for exactly the object where it matters most. So definition pins, purchase rights, and choosing installments insidepurchases[]wait for 4.0. In 4.0,commercial-termsgets a declared extension point with must-understand, which is what binding terms need.With that, holds, the
list_productsversion echo,product_ids_exclusive, and the installment parts on products and refinement all stay in 3.3. Pins, rights, and installment selection move to 4.0.I'll do the work: the reopening PR, DR-0036, and the check change. I'll link them here.
KonstantinMirin commentedon Oct 27, 2026
The three PRs are up:
adcp_versionecho.main, stacked on build(schemas): keep closed schemas closed within a major, with recorded corrections #8530. It reopens 24 locations and still rejects the three legacy keys the closure used to reject.3.2.x, with no 3.3 fields.Two updates to my earlier comment. Installment selection waits for 4.0 as a whole: its refinement fields are checked against the installments in
purchases[], which wait, so they can't ship alone. The installment fields on products stay. Later-proposal consent does ship: reopeningopportunity-contextlets it through. @bokelley, can you confirm you're OK with that?On #8523 and #8524: they implement correction (b), so they add their entries to the corrections file that #8530 introduces. Once #8531 lands, #8523 may need fewer entries, because (a) already covers the proposal-flow responses.
bokelley commentedon Oct 27, 2026
Maintainer decisions (2026-10-27): aligned with your plan, @KonstantinMirin.
DR-0036 one-time correction: yes. Reopen the 3.2 proposal flow (build(schemas): keep closed schemas closed within a major, with recorded corrections #8530, fix(schemas): reopen the 3.2 proposal-flow schemas closed against DR-0019 #8531, fix(schemas): reopen the proposal-flow schemas closed against DR-0019 on 3.2.x (#8501) #8532). I'll merge them as they go green; they touch gated paths.
Later-proposal consent ships in 3.3: confirmed (
opportunity-contextreopened).commercial-termsstays closed: agreed. Moving to 4.0, where commercial-terms gets a declared extension point with must-understand:purchases[].Staying in 3.3, as you listed: holds, the
list_productsversion echo,product_ids_exclusive, and the installment fields on products and in refinement.feat(media-buy): seller offers on accepted buys #8102 splits: the offer lane ships where its fields land on reopened, non-commercial-terms objects. The seller-held allowance lane (
holder/purchase_indexonchange-term, inside commercial terms) moves to 4.0.Capabilities byte cap (Spec tension: creative.supported_formats pushes capabilities past the 64 KiB that gates signing-key discovery #8198/spec(capabilities): structural bounds are the limit; the byte cap is a deployment backstop #8526): see Spec tension: creative.supported_formats pushes capabilities past the 64 KiB that gates signing-key discovery #8198. It stays as a backstop only.
build(schemas): keep closed schemas closed within a major, with recor…
fix(schemas): reopen the proposal-flow schemas closed against DR-0019…
bokelley commentedon Oct 30, 2026
4.0 work list from this thread, async (the Nov 2 session is cancelled; objections and owner volunteers by Fri 2026-11-06):
commercial-termsgets a declared extension point with must-understand. It brings back definition pins, purchase rights, installment selection inpurchases[], and seller-held adjustable terms (holder/purchase_index). Proposed owner: @KonstantinMirin.maxItems/maxLengthon stable fields from the bounds inventory. 3.3 enforces bounds only on new and experimental fields.adcp_major_version, the natural-key account reference after provisioning, the identity-rekey machinery,principal_kind, and the RFC 9421 signing profiles.Tracked in the v4 compatibility registry. Reply with objections or to take an item.
bokelley commentedon Oct 31, 2026
@KonstantinMirin: one ask on the GA path for 3.3 (#8600).
scripts/lint-additive-minor-baseline.jsonstill has 26 entries marked "pending WG decision". Could you post a disposition table here: each entry with one of (a) move to the nearest open parent, (b) record a DR-0036 correction, with the spec text it restores, or (c) defer to 4.0 and withdraw from 3.3? We'll approve it by consent, with objections by Fri 2026-11-13, and land the moves before the GA beta (target: week of Nov 16). Happy for you to own the PRs, or tell us which ones you'd like taken off your plate.docs(governance): propose DR-0032 and DR-0033 (parked pending #8501)
98 remaining items
docs(reference): resolve the #8762 and #8957 markers in the 3.3 relea…
docs(reference): resolve the #8767 markers and describe the withdrawn…
docs(reference): bring the 3.3 release docs to 3.3.0-rc.0
docs(reference): resolve the #8762 and #8957 markers in the 3.3 relea…
docs(reference): resolve the #8767 markers and describe the withdrawn…
docs(reference): bring the 3.3 release docs to 3.3.0-rc.0
docs(reference): resolve the #8762 and #8957 markers in the 3.3 relea…
docs(reference): resolve the #8767 markers and describe the withdrawn…
docs(reference): write #8854 up as in review, not in rc.0
docs(reference): bring the 3.3 release docs to 3.3.0-rc.0
docs(reference): resolve the #8762 and #8957 markers in the 3.3 relea…
docs(reference): resolve the #8767 markers and describe the withdrawn…
docs(reference): write #8854 up as in review, not in rc.0
docs(reference): bring the 3.3 release docs to 3.3.0-rc.0 (#8883)
schemas: withdraw metric_id and restore evaluator as deprecated (#8501 …