A missing value occurs when a field is omitted rather than explicitly assigned. APIs must distinguish omission from an explicit null, because each can express a different user intention. section 5.1.1
Treat these states as distinct unless the API deliberately defines otherwise:
- An ordinary value supplies data, such as a fruit color of "red". section 5.1.1
- An empty string supplies a value, even though that value contains no characters. section 5.1.1
- An explicit null supplies a non-value and may instruct an update to set the field to null. section 5.1.1 section 8.3.5
- A missing field supplies no field value; in an inferred field mask, it usually means the field is not being updated. section 8.3.5
Removing a dynamic key
To remove the test key from a ChatRoom settings map, send an explicit field mask while omitting the field from the request body: PATCH /chatRooms/1?fieldMask=settings.test with {} as the body. This removes the key rather than assigning it null. section 8.3.6
fruit1 = { name: "Apple", color: "red" };
fruit2 = { name: "Apple", color: "" };
fruit3 = { name: "Apple", color: null };
fruit4 = { name: "Apple" };
Compare an ordinary value, an empty string, an explicit null, and an omitted color field in otherwise identical Fruit objects. section 5.1.1
Do not use a zero value as a default marker when zero is also meaningful: doing so prevents callers from expressing an intentional zero and makes behavior unpredictable. section 5.3.2 section 5.2
