Skip to content

4.0: one UPPER_SNAKE_CASE vocabulary for error, reason and outcome codes, defined per protocol and checked by the build #8885

Open

Description

@KonstantinMirin

Problem

AdCP has many vocabularies of codes: errors, refusal and decline reasons, and reason codes on outcomes. They don't agree on spelling or on where a code lives. On main (18da1a4559), 61 enum positions carry a code or a reason, and 306 of their 481 current values are lower_snake_case. The main vocabularies:

Vocabulary Values Casing Where it's carried
enums/error-code.json 122, plus 2 deprecated UPPER_SNAKE_CASE error.code
enums/request-signing-error-code.json 29 lower_snake_case WWW-Authenticate: Signature error="..."
trusted-match/error.json code 7 lower_snake_case trusted-match error.code
enums/snapshot-unavailable-reason.json 3 UPPER_SNAKE_CASE delivery snapshot
enums/action-not-allowed-reason.json 5 lower_snake_case details of ACTION_NOT_ALLOWED
enums/creative-merge-rejection-reason.json 4 lower_snake_case details of CREATIVE_MERGE_REJECTED
enums/seller-policy-decline-reason.json 7 lower_snake_case declined control request
enums/proposal-decline-reason.json 10 lower_snake_case decline_proposals
enums/proposal-refinement-reason.json 8 lower_snake_case partially applied revision
enums/impairment-reason-code.json 11 lower_snake_case impaired media buy
enums/creative-event-reason-code.json 17 lower_snake_case creative lifecycle webhooks
enums/macro-resolution-reason.json 12 lower_snake_case macro preflight result
enums/offer-reason.json 5 lower_snake_case seller offer
enums/later-proposal-reason.json 5 lower_snake_case later proposal
enums/media-buy-lineage-reason.json 5 lower_snake_case successor media buy
enums/warning-code.json 3 lower_snake_case warnings[].code

Nine conditions are already spelled both ways, such as ACCOUNT_SUSPENDED and account_suspended. #8884 adds a tenth for 3.3, error code UNRECOGNIZED_TERMS beside decline reason unrecognized_terms, and proposal-refinement-reason already has uninterpreted, which is close to it. Error codes are also one flat list of 122 in core, although most of them belong to one protocol.

Apart from the request-signing codes, which the schema keeps lowercase on purpose as a transport profile, none of this drift was a decision. Each vocabulary was written by hand, and nothing in the schema build checks a new enum against the others.

Proposal for 4.0

This covers codes and reasons only. Other enum values are left to #8901, which lints every value and gives five tokens one spelling. Under item 2, codes and reasons are one vocabulary, so they need one spelling. Putting them all in UPPER_SNAKE_CASE goes beyond Brian's position on #8901: besides the nine conditions above, it renames about 225 lowercase reasons and codes that have one spelling today, such as price and back_in_stock. Both issues are on the Dec 18 freeze in #8756, to be decided together.

  1. One spelling, no exceptions. Every error, reason and outcome code is UPPER_SNAKE_CASE, including the request-signing codes. An HTTP auth-param value can be uppercase (RFC 9110 §11.2), so the header doesn't need a different spelling.

  2. Defined once, referenced everywhere. A field that carries a reason or a code references the code vocabulary instead of declaring its own enum. A condition has one code, whether it comes back as an error or as the reason on a request that succeeded, such as a decline. For a protocol's condition, that is the prefixed code from item 4 on both channels. What stays different is the channel: an error means the request failed, and a reason rides on a response or request that succeeded.

  3. Each protocol defines its codes by convention, and the build publishes one list. Every protocol in enums/adcp-protocol.json has an error-codes.json that follows one shared schema: each code with its description and metadata. Trusted Match, which that enum doesn't list, has one too, and so do the core layers, accounts among them. The build generates enums/error-code.json from those files, so an implementer still imports everything from one file, and nobody maintains it by hand. error.code in core/error.json stays an open string, as it is today, and the generated list is what it documents as the standard codes. This follows the module boundary RFC: AdCP 4.0 — a fast, cleanup-first major (scope, principles, schedule) #8756 proposes, which maps onto protocols, so no new layer is added.

  4. A protocol's codes carry its prefix. This goes further still than Brian's position, and it's my own proposal. Each protocol's code file declares one prefix, such as MB_ or CR_, so a reader can tell which protocol produced a code. A code takes a protocol's prefix when it names that protocol's object, such as a package or a creative, or when only that protocol uses it, and keeps its whole name after it (CR_CREATIVE_NOT_FOUND). Codes that two protocols use, or that bind parties of two protocols, stay core with no prefix; UNRECOGNIZED_TERMS from feat(schemas): acceptance of signed commercial terms binds every member #8884 is one. Of the 166 distinct UPPER_SNAKE_CASE codes on main, 90 would take a prefix and 76 stay core.

  5. The metadata says how a code is carried, not only how to recover. Each code already has enumMetadata with recovery and suggestion. Some codes also have a transport obligation: the request-signing codes go back in WWW-Authenticate: Signature error="<code>", and today only the prose description says so. I'd add that obligation to the code's metadata, for example "http_header": { "name": "WWW-Authenticate", "scheme": "Signature", "param": "error" }. It's part of the wire, so it belongs in the spec.

  6. The build enforces it. The schema build fails when:

    • a code doesn't match ^[A-Z][A-Z0-9_]*$, or lacks its metadata (values deprecated with x-deprecated-enum-values are skipped);
    • a code in a protocol's file doesn't start with that file's prefix;
    • the same code is defined in two files;
    • a protocol's code file is missing from the generated list;
    • a property that carries a reason or a code (code, reason, reasons, error, and names ending in _code, _reason, _codes or _reasons) declares its own enum instead of referencing the list.

    With that check from 4.0.0, a new vocabulary can't drift again.

Why 4.0

Renaming an enum value breaks every receiver that matches on it, so this needs the major. I'd rename in 4.0.0 with the breaking-change notice, as I've proposed for the T2 renames on #8756. Readers fetch brand.json and adagents.json without negotiating a version, so there 4.0.0 adds the new code and deprecates the lowercase one, which publishers keep sending through 4.x. Items 3 and 5 change no wire value. It fits #8756's T2 (one definition per concept, one schema architecture) and T3 (the evolution contract).

I'm happy to take this on.

Revised 2026-11-12: scope measured on main and set against #8901; protocol prefixes added; 4.0 timing.

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