Repository navigation
Description
Problem
An AdCP enum value becomes an identifier in many implementations, and nothing in the schema build checks that it works as one. #8791 found positions where it doesn't: clickTag beside clickTAG, Python keywords (pass, global), and the enum-protocol names name and value. The steps in Brian's ruling fix them (#8915 in 3.3, removals and renames in 4.0), apart from the four name positions #8791 declined, which stay as ruled. Nothing stops the next one.
Separately, five tokens are spelled two ways for one concept, such as the protocol name: media-buy in enums/adcp-protocol.json, media_buy in supported_protocols.
Measured on static/schemas/source at main 18da1a4559: 2,658 string enum, const and vocabulary sites, 7,198 values, including 121 deprecated sites, which the checks leave out.
| Check | Positions on main |
|---|---|
| Sibling values equal once case and separators are folded | 1 site: clickTag / clickTAG |
| Values equal to a reserved word of Python, Go, Java or TypeScript, case included | 51: pass ×3 and global, which #8915 deprecates, and 47 that cause no problem, such as package ×11, public ×9 and range ×3 |
Values equal to an enum-protocol name, an attribute or method every Python or Java enum has (name, value, values, ordinal, valueOf) |
12: 8 covered by the ruling's steps, and the 4 name positions #8791 declined |
Proposal for 4.0
No blanket rename. Values keep their spelling, apart from item 4.
- No sibling collisions. Within one enum, and across the
constvalues of one discriminator, no two values are equal after lowercasing and removing everything but letters and digits. Folding separators is one step beyond Enum values collide with SDK target languages' reserved words and enum protocol — 16 positions, two of them unexpressable in Go and Java #8791's case folding: it catchesmedia-buybesidemedia_buy, which map to one identifier just asclickTagandclickTAGdo. Main has no collision across its 157constdiscriminators. - No reserved words. No value equals a reserved word of Python, Go, Java or TypeScript, or an enum-protocol name in Python or Java. The match is exact, case included. A case-insensitive match would flag
noneat 35 positions because Python reservesNone, though nothing reservesnone. - A baseline that only shrinks. Today's positions go into a baseline. From the day the check lands, it blocks any new value that would add to the baseline, so every new vocabulary starts clean. At 4.0.0, rule 1's baseline is empty, because
clicktag_macrobecomes a pattern. Rule 2's keeps the 47 keywords that cause no problem and the fournamepositions Enum values collide with SDK target languages' reserved words and enum protocol — 16 positions, two of them unexpressable in Go and Java #8791 declined; one of those also listsrange, which is among the 47. Deprecated values (x-deprecated-enum-values) are skipped, so the originals feat(schema): add reserved-word-safe replacements for 6 enum positions and deprecate the originals (#8791) #8915 keeps don't count. - One spelling for the five tokens spelled two ways. Each is one concept with two spellings today. A token with an experimental side new in 3.3 changes before the 3.3 RC; one whose sides are both stable changes in 4.0. When only one side is stable, the token takes that spelling. Otherwise it takes lower_snake_case, which 2,508 values use against 75 in kebab-case, with an underscore between its words:
media_buy,non_linear,under_delivery. So three change before the RC and two in 4.0.
| Concept | Today | One spelling |
|---|---|---|
| Protocol name | media-buy in enums/adcp-protocol.json, the manifest's tool protocol, the verification token role and the task domain, and sponsored-intelligence in the first three; media_buy and sponsored_intelligence in supported_protocols and the protocols filter |
media_buy and sponsored_intelligence wherever a protocol is named, in 4.0. The manifest's other kebab-case protocol values move with them. Specialism IDs are their own vocabulary and stay. |
| Input required | input-required in enums/task-status.json, whose values come from A2A's task states; input_required in enums/execution-readiness-status.json |
input-required, before the 3.3 RC: execution readiness is new in 3.3. Task status keeps the spelling the A2A guide normalizes A2A's TASK_STATE_INPUT_REQUIRED to. |
| Click-through URL | clickthrough in enums/url-asset-type.json; click_through in enums/creative-change-kind.json |
clickthrough, before the 3.3 RC: creative-change-kind is new in 3.3, and its own description already says url_type clickthrough. |
| Non-linear | nonlinear in the video_vast creative_type; non_linear in the VAST tracker target |
non_linear, in 4.0, as the tracker target has it beside linear and companion. |
| Under-delivery | underdelivery in enums/delivery-projection-end-state.json; under_delivery in enums/offer-reason.json |
under_delivery, before the 3.3 RC: both enums are new in 3.3. |
The other tokens spelled two ways differ only in case, or name a different concept, or come from another spec, such as VAST's firstQuartile. #8885 covers the codes among them.
Every position, every site of every token and the scripts that list them are in this gist.
Why 4.0
The lint changes no wire value. Renaming a value breaks every receiver that compares it, so the two stable renames wait for the major, with the breaking-change notice. It fits #8756's T2 (one schema architecture), and it's decided together with #8885 at the Dec 18 freeze.
I'm happy to take this on.
Revised 2026-11-12: narrowed to Brian's position: the lint agreed on #8791, with separators folded as well as case, plus one spelling for the five tokens spelled two ways. The rename of every value to UPPER_SNAKE_CASE is dropped, along with its exemptions, the token rule and the check that identifier references exist.
Activity
bokelley commentedon Nov 12, 2026
Thanks for measuring the whole vocabulary. This belongs with the 4.0 scope decisions, so I'm leaving it open for the Dec 18 freeze in #8756 rather than deciding it here. My position going in:
UPPER_SNAKE_CASE. It changes about 6,400 wire values for every implementer, and generated code already maps case. What hurts SDKs is collisions and reserved words, not mixed case.If the WG wants a different line, the freeze is the place to settle it.
KonstantinMirin commentedon Nov 12, 2026
Thanks, Brian. That works for me: no blanket rename, the #8791 lint, with separators folded too, and one spelling for the five.
The five (main
18da1a4559):media-buyinadcp-protocol,media_buyinsupported_protocols, withsponsored-intelligence.input-requiredin task status,input_requiredin execution readiness.clickthroughin URL asset types,click_throughin creative change kinds.nonlinearinvideo_vast,non_linearin VAST tracker targets.underdeliveryin delivery projections,under_deliveryin offer reasons.The other tokens spelled two ways (50 in all, in the gist) differ only in case, come from another spec or name different things.
Three needn't wait for 4.0: the side that changes is new in 3.3, experimental and only in the betas. Before the RC,
input_requiredcan take task status's A2A spellinginput-required,click_throughcan becomeclickthroughandunderdeliveryunder_delivery, with no stable release touched, thoughunderdeliveryis in DR-0029 and has one adopter. I can open that PR today if you'd like.#8885 goes beyond your position: UPPER_SNAKE_CASE for every code and reason renames about 225 lowercase reasons and codes that have one spelling today, and its protocol prefixes go further still. I'll say so there, for the freeze.
[-]4.0: UPPER_SNAKE_CASE for every AdCP-defined enum value and discriminator, checked by the build[/-][+]4.0: enum-value lint (case-fold collisions, reserved words) and one spelling for the five tokens spelled two ways[/+]fix(schemas): spell three experimental 3.3 values as their counterpar…