Agent WranglersRequests and responses Recommended
Use enums for fixed values
Give every field with a fixed set of values an enum in the contract, and document what each value means.
How to do it
Use stable lowercase strings, such as "pending" and "shipped". Tell clients to treat an unknown value as a safe default, because you may add values later.
How to check
Every status or type field in the OpenAPI file has enum, and a client test with an unknown value does not crash.
For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/requests-and-responses/api-enums.