Skip to content

4.0: enum-value lint (case-fold collisions, reserved words) and one spelling for the five tokens spelled two ways #8901

Open

Description

@KonstantinMirin

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.

  1. No sibling collisions. Within one enum, and across the const values 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 catches media-buy beside media_buy, which map to one identifier just as clickTag and clickTAG do. Main has no collision across its 157 const discriminators.
  2. 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 none at 35 positions because Python reserves None, though nothing reserves none.
  3. 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_macro becomes a pattern. Rule 2's keeps the 47 keywords that cause no problem and the four name positions 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 lists range, 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.
  4. 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

  1. added this to the 4.0 milestone on Nov 11, 2026
  2. added
    schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    on Nov 11, 2026
  3. bokelley commented on Nov 12, 2026

    @bokelley
    Contributor

    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:

    If the WG wants a different line, the freeze is the place to settle it.

  4. KonstantinMirin commented on Nov 12, 2026

    @KonstantinMirin
    CollaboratorAuthor

    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):

    1. Protocol names: media-buy in adcp-protocol, media_buy in supported_protocols, with sponsored-intelligence.
    2. input-required in task status, input_required in execution readiness.
    3. clickthrough in URL asset types, click_through in creative change kinds.
    4. nonlinear in video_vast, non_linear in VAST tracker targets.
    5. underdelivery in delivery projections, under_delivery in 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_required can take task status's A2A spelling input-required, click_through can become clickthrough and underdelivery under_delivery, with no stable release touched, though underdelivery is 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.

  5. changed the title [-]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[/+] on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasschemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygienespec / protocol

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions