← Daily

Concept · No. 035 · November 20, 2026

Adding an enum value is a breaking change for most clients

Every enum in an API response is a promise about which strings can appear. Servers treat new values as additive, while many clients treat them as a parse error, and the gap shows up as an outage in an app version you cannot recall.

The idea

A field like status or type usually starts as a small fixed set. The server team sees adding a value as backward compatible: no field removed, no type changed. Many clients see it differently. A strict deserializer rejects the unknown string, an exhaustive when or switch has no branch for it, and a generated client may refuse the whole payload.

The concept worth internalising is that an enum on the wire is an open set, whatever the schema says. Designing for that means two things: the contract states that new values may appear, and every client has a defined, conservative behaviour for a value it does not recognise.

An example

An order API returns status with values pending, paid, shipped and delivered. The server team adds partially_shipped to support split fulfilment.

  • The web client deploys continuously and picks up the new value the same day.
  • An older mobile build uses a JVM client where Jackson's default is to fail on unknown enum values. Deserialising the order list throws.
  • The failure is not limited to the one split order. The entire list response fails to parse, so the screen shows an error for every user who has any split order.
  • That mobile build stays installed for a long time, and the server cannot force an upgrade.

The server change was correct. The contract was what failed: nothing told the client that status could grow.

Where it breaks

A fallback is not automatically safe. If an unknown refund state is mapped to the nearest familiar value, such as treating it as completed, the client now displays something false. The fallback must be the cautious reading: show a neutral label, disable actions that depend on the state, and log the raw value.

Some new values carry obligations, not just labels. A new payment state that requires the user to confirm a charge cannot be handled by a generic unknown branch, because doing nothing is wrong. In that case a new field, a capability negotiation, or a new version is the honest choice.

Direction matters too. Accepting new values on input is cheap. Emitting new values in output is where clients break, so treat output enums with more care than input enums.

A few sets really are closed, such as a boolean-like flag. Those are better modelled as booleans than as enums with a promise of growth.

In practice

I would start with the contract and the client libraries, then add server-side protection for clients you cannot update.

  • State in the API description that enum values may be added. OpenAPI has no built-in open enum, so say it in the field description or use a convention such as x-extensible-enum.
  • In protobuf, make the first value UNSPECIFIED and rely on unknown values being preserved instead of dropped.
  • In generated JVM clients, enable READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE and mark an UNKNOWN constant with @JsonEnumDefaultValue.
  • In Kotlin or Swift, model wire enums with an Unknown(raw: String) case so the original value survives for logs and round trips.
  • Write one contract test per client that feeds an unrecognised value and asserts the screen still renders.
  • For known-strict clients, gate new values on a client version or capability header and send them the closest safe existing value until they upgrade.
  • Review new enum values the way you review removed fields, because for strict clients they behave the same.
Treat every output enum as an open set: document that it can grow, give every client a conservative unknown branch, and test that branch before you add a value.