How Can an API Describe Enumerated Values?
From the earlier reference collection. Read the current software blog.
List allowed values, explain what each means, and describe how clients should handle future additions.
Give each code a defined meaning
An enumerated field accepts a limited set of values, such as a status that may be open, closed, or unknown. The schema should list the exact values and explain their meanings. A list alone leaves clients guessing whether closed means temporarily unavailable or permanently retired.
Document spelling, capitalization, and whether values are strings or numbers. If OPEN and open are not interchangeable, say so. Consistent canonical values prevent simple comparisons from failing because one client normalized capitalization while another did not.
Keep unknown distinct from new
A value called unknown can mean that the publisher does not know the current state. It should not be confused with an unrecognized code that a client has never seen. If a future release introduces maintenance, an older client may receive a value that was validly added after it was written.
Explain the extension policy: may new values appear without a major version change, and should clients preserve or display unfamiliar values? A robust client can retain the raw token and show a neutral fallback instead of crashing or silently mapping it to a misleading known state.
Avoid encoding many facts in one code
If statuses combine independent dimensions, an enum can grow confusingly. Values like open_with_warning and closed_with_warning may indicate that operating state and warning presence are separate properties. Two fields can be clearer when clients need to reason about each dimension independently.
Enums are still useful when choices are mutually exclusive and stable. Keep the set focused and avoid using a code to smuggle explanatory prose that belongs in a separate message or detail field.
Show examples and validation behavior
Provide a sample record for each important state, including any deprecated value and its replacement. Define whether input is rejected, warned about, or preserved when an unknown value is encountered; output clients also need to know how to behave when the service adds one.
A clear enum contract helps teams validate records consistently while allowing the interface to evolve. Exact tokens, plain definitions, and a future-value policy make the field practical for both current and older clients.