A default value is selected when an API request or data field omits an explicit choice. Good defaults express the user’s lack of preference while preserving predictable behavior. Omitting a field can differ from supplying an empty, zero, false, or null value, so the API must define those distinctions clearly. section 5.0 section 5.3.2
Choose default representations according to the data type and serialization constraints:
- Prefer positive Boolean names such as allowChatbots, but avoid encoding a permanent policy choice in the field name when future defaults may change. section 5.2
- Avoid using numeric zero as a default marker when zero is also a meaningful value; otherwise users cannot intentionally request zero. section 5.3.2
- Use an empty string as a default marker only when it is invalid, or reserve an explicit choice such as "default" when empty is valid. section 5.4.2
- Do not treat an empty list as a default request when an empty list is a legitimate value; apply the default at creation or model the data as a subcollection. section 5.6.3
- For field masks, return all fields by default unless unusually large or expensive fields would seriously harm retrieval; document every exclusion. section 8.3.4
A Boolean default in a chat-room API
A ChatRoom may expose archived and allowChatbots fields. If the serialization format collapses an omitted Boolean into false, the API cannot distinguish “choose the usual policy” from an explicit prohibition. Naming and representation should therefore be chosen with both the current default and future policy changes in mind. section 5.2
Defaults should be stable, unsurprising, and visible in documentation. Treat sentinel values as part of the API contract, and do not sacrifice an intentional value merely to represent “do what is best.” section 5.3.2 section 8.3.4
