Enum Evolution: The New Value That Broke Old Clients

The provider's view: status was active | inactive, the product now needs suspended, adding an enum value changes no field, no type, no endpoint — it goes out as a routine deploy. The consumer's view: their code was written against a *closed set*, because that is what the word "enum" told them. Exhaustive switches, lookup tables keyed by value, database CHECK constraints mirroring the enum, UI mappings from value to badge color — every one of these encodes the assumption that the set is complete.

What happens next depends on the client's failure mode, and all of them are bad. The strict client throws on deserialization and the whole response is lost — a list endpoint returning one suspended user takes down the entire user list. The defensive client hits default: and hides the record, so suspended users silently vanish from admin screens. The dangerous client falls through to a *default value* — and if that default is active, a suspended account just kept its access. The same shape recurs on the wire: a payment state enum gaining disputed, a webhook event type gaining a new event, an error code enum gaining a new code (see An Error Taxonomy Clients Can Branch On).

The uncomfortable verdict: adding a returned enum value is additive for the schema and breaking for behavior — unless the contract said, from day one, that the set is open. This is the single most common "safe" change that is not, which is why it gets its own lesson rather than a row in Backward Compatibility: The Real Rules.

Not every enum should be open. Enums the *client sends* (request enums) are naturally closed from the client's perspective — a client cannot send a value it does not know — and the server validates against its current set, rejecting unknowns with a clear Validation Errors: Feedback, Not Verdicts response. The evolution question is almost entirely about enums the *server returns*.

For returned enums, you have three honest designs. Closed: the set is frozen; adding a value is declared a breaking change and routed through Versioning: What a Version Even Promises or a new field. Right for tiny, genuinely complete sets (currency_side: debit | credit). Open: the set grows; clients are contractually required to handle unknowns, with per-field guidance on what safe degradation means. Right for anything reflecting a business process — statuses, event types, reasons — because business processes grow states. Open with `other`: the server itself maps rare or new cases to a documented catch-all, often paired with a free-text detail field. Right when you want old clients to receive a *stable* value rather than an unknown one — at the cost that they cannot distinguish new cases.

Protobuf made a version of this choice for you: proto3 enums decode unknown wire values into an "unrecognized" representation instead of failing, and the convention of a zero-valued _UNSPECIFIED entry exists precisely because absent and unknown must be distinguishable (see gRPC: Schema, Codegen and Streams). JSON APIs have no such floor — the openness rule exists only if you write it.

The clause that prevents all of this costs four sentences in the field's documentation, and it must exist *before* the first client ships — retrofitting it is asking every existing consumer to change, which is exactly the migration the clause was meant to avoid. It needs four parts: the set is extensible; unknown values will appear without a version bump; what safe handling means for this field specifically; and where new values are announced. "Handle it gracefully" is not guidance — for an account status, safe means "treat as neither active nor deleted; do not grant access; display neutrally", and that sentence is the actual contract.

Status enums usually front a state machine, and adding a value means adding a *state* — so the transition rules must evolve with it (see Resources Have State Machines). Old clients do not just render suspended; they decide which buttons to show, and a client that offers "deactivate" on a state it does not understand may be issuing transitions the machine now rejects. The contract answer: servers reject invalid transitions with a Status Codes Clients Can Branch On-honest 409 regardless of client vintage, and clients derive available actions from the API (an available_actions array or HATEOAS-ish links) rather than hardcoding action rules per status. That moves state-machine evolution entirely to the server — the one place you can deploy.

Finally, test the openness claim. A contract test that returns status: "zz_test_unknown" to each SDK and asserts graceful handling turns the clause from documentation into a verified property (see Testing the Contract, Not Just the Code and SDK Design: The Contract's User Interface) — generated SDKs in strict languages are the usual offenders, mapping enums to closed native types that throw on novelty.