A dynamic data structure permits keys or fields to be present, explicitly null, or absent. JSON objects and maps use this flexibility, but APIs must define how each state behaves. section 5.1.1 section 8.3.6
Design dynamic structures deliberately:
- Distinguish a value, explicit null, and a missing key; treating them alike creates inconsistent requests and responses. section 5.1.1
- Use field masks for partial updates: an omitted field is not selected, while a null field is selected and set to null. section 8.3.5
- Remove keys with an explicit field-mask operation rather than inventing an undefined value that JSON cannot represent. section 8.3.6
Removing a map key
To remove the test key from a ChatRoom settings map, send PATCH /chatRooms/1?fieldMask=settings.test with an empty JSON body. The mask identifies the key for removal without encoding undefined. section 8.3.6
fruit1 = { name: "Apple", color: "red" };
fruit2 = { name: "Apple", color: "" };
fruit3 = { name: "Apple", color: null };
fruit4 = { name: "Apple" };
Compare a concrete value, an empty string, explicit null, and a missing color in otherwise similar Fruit objects. section 5.1.1
