Agent WranglersRequests and responses Required
Give every response one shape
Return the same fields of the same types every time, and describe them in the contract. Leave out a field only when the contract says it is optional.
How to do it
Decide per field whether it is required. Never switch a field between an object, a list and null. See one return type. Return only the fields a caller may see, as in only needed fields.
How to check
Contract tests validate every response against its schema with additionalProperties: false, and they pass.
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/response-shape.