Field behavior documentation
When defining fields in protocol buffers, it is customary to explain to users certain aspects of the field's behavior (such as whether it is required or optional). Additionally, it can be useful for other tools to understand this behavior (for example, to optimize client library signatures).
APIs should use the
google.api.field_behavior annotation to describe
well-understood field behavior, such as a field's being required, immutable, or
// The audio data to be recognized. RecognitionAudio audio = 2 [(google.api.field_behavior) = REQUIRED];
Additionally, APIs may use the
OPTIONAL value to describe none of the
above. However, it is never mandatory to explicitly describe a field as
Note: The vocabulary given in this document is for descriptive purposes only, and does not itself add any validation. The purpose is to consistently document this behavior for users.
The use of
REQUIRED indicates that the field must be present (and set to
a non-empty value) on the request or resource.
A field should only be described as required if either:
- It is a field on a resource that a user provides somewhere as input. In this case, the resource is only valid if a "truthy" value is stored.
- It is a field on a request message (a message that is an argument to an RPC,
with a name usually ending in
Request). In this case, a value must be provided as part of the request, and failure to do so must cause an error (usually
We define the term "truthy" above as follows:
- For primitives, values other than
0.0, empty string/bytes, and
- For repeated fields maps, values with at least one entry
- For messages, any message with at least one "truthy" field.
Fields should not be described as required in order to signify:
- A field which will always be present in a response.
- A field which is conditionally required in some situations.
- A field on any message (including messages that are resources) which is never used as user input.
Note: In most cases, empty values (such as
false for booleans,
integers, or the unspecified value for enums) are indistinguishable from unset
values, and therefore setting a required field to a falsy value yields an
error. A corollary to this is that a required boolean must be set to
The use of
OUTPUT_ONLY indicates that the field is provided in responses, but
that including the field in a message in a request does nothing (the server
must clear out any value in this field and must not throw an error as a
result of the presence of a value in this field on input). Similarly, services
must ignore the presence of output only fields in update field masks.
Additionally, a field should only be described as output only if it is a
field in a resource message, or a field of a message farther down the tree.
Notably, fields in response messages (a message which only ever acts as a
return value to an RPC, usually ending in
Response) should not be
described as output only because this is already implied.
Output only fields may be set to empty values if appropriate to the API.
Potential use cases for output only fields (this is not an exhaustive list) are:
- Create or update timestamps.
- Derived or structured information based on original user input.
- Properties of a resource assigned by the service which can not be altered.
The use of
INPUT_ONLY indicates that the field is provided in requests and
that the corresponding field will not be included in output.
Additionally, a field should only be described as input only if it is a
field in a resource message or a field of a message included within a resource
message. Notably, fields in request messages (a message which only ever acts as
an argument to an RPC, with a name usually ending in
Request) should not
be described as input only because this is already implied.
Potential use cases for input only fields (this is not an exhaustive list) are:
ttlfield as described in AIP-214.
Warning: Input only fields are rare and should be considered carefully before use.
The use of
IMMUTABLE indicates that a field may be set once in a request to
create a resource but may not be changed thereafter.
Additionally, a field should only be described as immutable if it is a
field on a request message (a message that is an argument to an RPC, usually
Request), or a field of a message included within a request
When a service receives an immutable field in an update request (or similar),
even if included in the update mask, the service should ignore the field if
the value matches, but should error with
INVALID_ARGUMENT if a change is
Potential use cases for immutable fields (this is not an exhaustive list) are:
- Names or IDs which are set on creation and then used as a primary key.
Note: Fields which are "conditionally immutable" must not be given the immutable annotation.
The use of
OPTIONAL indicates that a field is not required, nor covered by
any of the above descriptions.
A field may be described as optional if none of the above vocabulary
applies, and it is a field on a request message (a message that is an argument
to an RPC, usually ending in
Request), or a field on a submessage, but it is
not mandatory to describe optional fields in this way.
If you do choose to explicitly describe a field as optional, ensure that every optional field on the message has this indicator. Within a single message, either all optional fields should be indicated, or none of them should be.
The use of
UNORDERED_LIST on a repeated field of a resource indicates that
the service does not guarantee the order of the items in the list.
A field should be described as an unordered list if the service does not guarantee that the order of the elements in the list will match the order that the user sent, including a situation where the service will sort the list on the user's behalf.
A resource with an unordered list may return the list in a stable order, or may return the list in a randomized, unstable order.
- 2020-12-15: Added guidance for
- 2020-05-27: Clarify behavior when receiving an immutable field in an update.
- 2019-12-05: Added guidance on output only fields in field masks.
- 2019-06-18: Use the machine-readable annotation, not comments.