Backward Compatibility Rules

There are a few simple rules, and a couple of exceptions.

• Requests: do not add mandatories (e.g. adding a new mandatory field, making an optional field mandatory)
• Responses: do not remove mandatories (e.g. remove a mandatory field, make a mandatory field optional)
• Do not change value types (e.g. int to string)

Requests

Do not add mandatory keys and / or make values non-nullable for existing keys.

Operation	Verdict	Reason
Add a mandatory key	incompatible	Existing consumers must send a key that they were not sending before.
Add an optional key	compatible	Existing consumers are not sending this key anyway, but new consumers may do so.
Remove a mandatory key	incompatible (exception)	EXCEPTION Consumers can send the key but server will henceforth ignore it, which could break consumers assumptions.
Remove an optional key	incompatible (exception)	If consumers choose to send the key, the server will now ignore it, which could break consumers assumptions.
Optional key becomes mandatory	incompatible	Consumers who were not sending this key before will now be expected to send it.
Mandatory key becomes optional	compatible	Consumers who were sending this key before can either continue sending it or stop sending it.

Responses

Do not remove mandatory keys and / or make values nullable for existing gkeys.

Operation	Verdict	Reason
Add a mandatory key	compatible	Older consumers were not expecting this key and will ignore it.
Add an optional key	compatible	Older consumers were not expecting this key and will ignore it. The server may or may not send it, and consumers should be prepared for either.
Remove a mandatory key	incompatible	Older consumers were expecting this key, but henceforth the response will not contain it.
Remove an optional key	incompatible	In some cases, the server used to send this in the response. Henceforth it never will.
Optional key becomes mandatory	compatbile	Sometimes the server didn’t send this key. But henceforth, the server will always send this key. Consumers who ignored it before can continue doing so. Consumers who checked for it before have code to handle it.
Mandatory key becomes optional	incompatible	It’s possible that the server will not send this key. Some consumers may be expecting it, but will not be receiving it henceforth.