diff --git a/aip/general/0180.md b/aip/general/0180.md index 7291f6487..82faad310 100644 --- a/aip/general/0180.md +++ b/aip/general/0180.md @@ -139,6 +139,93 @@ code, as such changes will be seen as breaking by those users. whether a proposed change is likely to break users, and an expansive reading of this guidance could ostensibly prevent _any_ change (which is not the intent). +#### Default values must not change + +Default values are the values set by servers for resources when they are not +specified by the client. This section only applies to static default values within +fields on resources and does not apply to dynamic defaults such as the default IP +address of a resource. + +Changing the default value is considered breaking and **must not** be done. The +default behavior for a resource is determined by its default values, and this +**must not** change across minor versions. + +For example: + +```proto +message Book { + string name = 1; + // The genre of the book + // If this is not set when the book is created, the field will be given a value of FICTION. + enum Genre { + UNSPECIFIED = 0; + FICTION = 1; + NONFICTION = 2; + } +} +``` + +Changing to: + +```proto +message Book { + string name = 1; + // The genre of the book + // If this is not set when the book is created, the field will be given a value of NONFICTION. + enum Genre { + UNSPECIFIED = 0; + FICTION = 1; + NONFICTION = 2; + } +} +``` + +would constitute a breaking change. + +#### Serializing defaults + +APIs **must not** change the way a field with a default value is serialized. For +example if a field does not appear in the response if the value is equal to the +default, the serialization **must not** change to include the field with the +default. Clients may depend on the presence or absence of a field in a resource +as semantically meaningful, so a change to how serialization is done for absent +values **must not** occur in a minor version. + +Consider the following proto, where the default value of `wheels` is `2`: + +```proto +// A representation of an automobile +message Automobile { + // The name of the automobile. + string name = 1; + + // The number of wheels on the automobile. + // The default value is 2, when no value is sent by the client. + int wheels = 2; +} +``` + +First the proto serializes to JSON when the value of `wheels` is `2` as follows: + +```json +{ + "name": "my-car" +} +``` + +Then, the API service changes the serialization to include `wheel` even if the +value is equal to the default value, `2` as follows: + +```json +{ + "name": "my-car", + "wheels": 2 +} +``` + +This constitutes a change that is not backwards compatible within a major +version. + ## Further reading - For compatibility around pagination, see [AIP-158][].