What Does Backward Compatibility Mean for an API Schema?
From the earlier reference collection. Read the current software blog.
A schema change is backward compatible when existing clients can continue to interpret responses and requests under the old contract.
Compatibility is about clients
An API schema describes names, types, required fields, and allowed values. A change is backward compatible only in relation to a client behavior: will a client built against the earlier contract still work with the changed service? Adding a field may be safe for clients that ignore unknown fields, but it can break strict decoders that reject them.
Changing a field from a number to text is usually disruptive because clients may parse or calculate with the former type. Renaming or removing a field can break any client that depends on it. Changing the meaning while keeping the name is also a compatibility break, even if the data type stays the same.
Review additions and restrictions
Making an optional response field required can break older producers or fixtures that omit it. Adding a new optional response field may be safe if clients tolerate unknown fields. For request bodies, adding a required field can break existing callers that do not send it. An optional request field is generally easier to introduce, provided omission retains its prior meaning.
Narrowing an allowed-value set can surprise clients if previously valid values are now rejected. Expanding an enum may also break clients that assume the list is exhaustive. Document whether consumers must handle unknown values, and consider an explicit fallback path in client code.
Announce changes with a migration path
For a breaking change, publish what changes, when it takes effect, and what clients need to update. A transition may expose the new field alongside the old one for a defined period, but only if both have clear semantics and a retirement plan. Avoid leaving deprecated fields indefinitely without explaining which one is authoritative.
Versioning can help consumers choose a contract, but a version label does not make incompatible behavior harmless. State whether a version changes the URL, media type, or another part of the request, and describe how long old versions remain available if that is part of the service's policy.
Test the contract in both directions
Keep representative old clients or fixtures and run them against the changed schema. Test decoding responses with unknown fields, omitted optional fields, nulls, and newly introduced values. For request changes, confirm that older requests still receive the documented behavior.
Before shipping, write down the compatibility claim and the client assumptions it depends on. If a change is safe only for clients that ignore unknown fields, say so and ensure the contract tells client authors to do that. Compatibility is a shared expectation, and explicit rules make changes easier to plan and less likely to surprise users.