Why direction decides whether a change breaks
Whether a schema change breaks clients depends on who reads the data. In a request the server is the reader, so tightening what it accepts breaks clients and loosening it is safe. In a response the client is the reader, so loosening what the server may send breaks clients and tightening it is usually safe.
A list of breaking edits, like the one in the OpenAPI breaking changes guide, covers the common cases. The direction rule covers the rest, including changes no list anticipated.
Requests: the server is the reader
Existing clients already send requests that passed the old rules. If the new rules reject any of those requests, some client breaks.
Tightening a request schema does exactly that. A new required field, a shorter maxLength, a removed enum value or a stricter format can turn a request that used to pass into a 400.
Loosening is safe in this direction. A schema that accepts everything it accepted before, plus more, rejects no request that used to succeed.
Responses: the client is the reader
Clients were written to handle every response the old schema allowed, and often nothing more. Suppose the server may now return something outside that set: a null, a new enum value, a missing field, or a string where a number was. Some client may then fail to parse it or act on it wrongly.
Tightening is usually safe here, because the server now sends a subset of what clients already handle. Making an optional response field always present is a typical example.
New response fields sit in between. Clients that follow the tolerant reader pattern, reading the fields they need and ignoring the rest, are unaffected. Clients that validate responses strictly against the old schema, especially one with additionalProperties: false, fail on any new field.
The same change in each direction
Each line names one schema edit and its effect in a request and in a response:
- Make a field required: breaks requests; safe in responses.
- Make a required field optional: safe in requests; breaks responses.
- Allow null: safe in requests; breaks responses.
- Add an enum value: safe in requests; can break responses for clients with closed enums.
- Remove an enum value: breaks requests; safe for parsing responses, though clients waiting for that value will never see it.
- Lower maxLength or add a pattern: breaks requests; safe in responses.
- Widen a type from integer to number: safe in requests; breaks responses for clients that parse integers.
- Add an optional property: safe in requests; safe in responses for tolerant readers only.
Schemas used in both directions
A component schema referenced by both a request body and a response has to pass both sets of rules. Most tightening breaks the request side and most loosening breaks the response side, so a shared schema is hard to change at all.
Split it into input and output schemas, such as OrderCreate for the request and Order for the response, so each can change under its own rule. Within one schema, readOnly marks properties that appear only in responses (an id or created_at), and writeOnly marks properties that appear only in requests (a password).
Webhooks and callbacks flip the roles. The provider sends the request and its consumers' servers read it, so a webhook payload follows the response rule: loosening it breaks consumers.