An enumeration constrains a textual value to one item from a predefined set. Prefer human-readable values such as "checking" and "savings" over cryptic codes, because consumers can interpret them without a separate dictionary. section 8.5.2
When legacy systems require numeric or abbreviated codes, retain the code but provide a neighboring label or an object containing both code and label. Dedicated dictionary operations can supply code meanings. section 8.5.2
Choose an enumeration with its consumers and future changes in mind:
- Use interpretable formats when values may grow; ISO 8601 durations such as P1M and P3M are more extensible than MONTHLY and QUARTERLY. section 15.6.3
- Prefer enumerations over Booleans when the domain may need more than two states, but recognize that consumers interpreting values can still break when a new state appears. section 15.6.3
- Treat expanding an input enumeration as backward compatible, while removing an accepted value or adding an output value can break consumers. section 15.2.1 section 15.2.2
Filtering by category
A transaction filter can accept multiple enumeration values: category=restaurant,bar or category=restaurant&category=bar. The same API can combine the enumeration with amount or date ranges. section 9.6.2
JSON Schema can make allowed values machine-readable for documentation, code generation, testing, and mocking tools. Add such precision after identifying the data and describing it textually. section 19.3
Figure 8.12 Contrasting non-human-readable and human-readable bank account type codes
Compare cryptic bank-account type codes with human-readable enumeration values and labels. section 8.5.2
