Repository navigation
Description
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.
-
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.
-
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.
-
Each protocol defines its codes by convention, and the build publishes one list. Every protocol in
enums/adcp-protocol.jsonhas anerror-codes.jsonthat 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 generatesenums/error-code.jsonfrom those files, so an implementer still imports everything from one file, and nobody maintains it by hand.error.codeincore/error.jsonstays 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. -
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_orCR_, 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_TERMSfrom 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. -
The metadata says how a code is carried, not only how to recover. Each code already has
enumMetadatawithrecoveryandsuggestion. Some codes also have a transport obligation: the request-signing codes go back inWWW-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. -
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 withx-deprecated-enum-valuesare 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,_codesor_reasons) declares its own enum instead of referencing the list.
With that check from 4.0.0, a new vocabulary can't drift again.
- a code doesn't match
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