Agent WranglersChanges over time Recommended
Tell clients to ignore what they don't know
Document that clients must ignore unknown fields and handle unknown enum values, so additions never break them.
How to do it
Say it in the API guide. Build your own SDKs and examples that way, and test them against responses with extra fields.
How to check
An SDK test feeds a response with an extra field and a new enum value. The client keeps working.
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/changes-over-time/tolerant-clients.