"Adding a field is always backward compatible" is one of the most repeated rules in API design, and it is not actually true. It's true for a consumer whose parser ignores keys it doesn't recognize. It's false the moment a consumer runs strict schema validation that rejects unrecognized properties, or deserializes your response into a generated type with an exhaustive shape. Compatibility is not a property of the JSON you send — it's a property of the JSON you send combined with what every actual consumer does when it meets something it wasn't built to expect, and for a public API, you don't control the second half of that equation.
This matters because a change that looks additive and safe on your side of the contract can still break a real integration on the other side, and it breaks silently in exactly the same way a mismatched protobuf field number breaks silently — a wrong or missing value with no error pointing at the actual cause. The rules in this lesson are sorted by how much of that risk you actually control: a small set of changes are safe no matter what a reasonable consumer does, a larger set are safe only if your contract explicitly commits consumers to a specific tolerant behavior, and a final set are never safe regardless of what anyone does downstream.
Get this classification wrong in either direction and it costs you differently. Treat a contract-dependent change as unconditionally safe and you break integrators who followed your documentation exactly. Treat a genuinely safe change as if it needs a full version bump and you pay a coordination and rollout cost for nothing. The point of this lesson is to be able to place any proposed change into the correct bucket before it ships, not after a support queue fills up with the same confused report from five different integrators.
Analogy🏏Cricket
🏏 Think of it like cricket: The Laws of Cricket are revised periodically by the sport's custodian body, and when a genuine change to how the game is played takes effect, it is announced in advance with a clear effective date, not slipped quietly into a future edition for umpires to discover mid-match. A change to how a specific dismissal is adjudicated, for instance, gets communicated to every board, every umpire panel, and every commentary team well before it applies to a single ball bowled in a real match, precisely because an umpire who is still working from the old law and a batsman who has been coached under the new one would produce a dispute that has nothing to do with either party being wrong — it would be two people correctly following two different contracts. An informal change made by one ground's officials because it seemed reasonable that day, without that same advance, universal communication, would create exactly that kind of chaos the very first time it mattered. Just as a genuine law change is announced with a clear effective date so every party updates from the same understanding at the same time, a genuinely breaking API change needs the same explicit, dated communication rather than a quiet shift consumers are expected to somehow keep up with. Just as an umpire correctly applying an outdated law isn't at fault for a resulting dispute, a consumer correctly following your documented contract isn't at fault when an undocumented assumption behind that contract turns out to have shifted. The insight is that compatibility is a shared understanding, not a unilateral decision, and the rules that actually hold are the ones both sides agreed to in advance.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.