AIP-203

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).

Guidance

APIs use the google.api.field_behavior annotation to describe well-understood field behavior, such as a field being required or immutable.

// The audio data to be recognized.
RecognitionAudio audio = 2 [(google.api.field_behavior) = REQUIRED];

• APIs must apply the google.api.field_behavior annotation on every field on a message or sub-message used in a request.
  • An exception to this is the AIP-154 etag field on a resource message, which should not have any google.api.field_behavior assigned.
  • Furthermore, oneof fields may omit google.api.field_behavior, but should document any specific behaviors in the comments in this case.
• The annotation must include any google.api.FieldBehavior values that accurately describe the behavior of the field.
  • FIELD_BEHAVIOR_UNSPECIFIED must not be used.
• APIs must at minimum use one of REQUIRED, OPTIONAL, or OUTPUT_ONLY.

Warning: Although field_behavior does not impact proto-level behavior, many clients (e.g. CLIs and SDKs) rely on them to generate code. Thoroughly review and consider which values are relevant when adding a new field.

Fields with no annotation are interpreted as OPTIONAL for backwards-compatility. Nontheless, this annotation must not be omitted.

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 clients.

field behavior of nested messages

google.api.field_behavior annotations on a nested message are independent of the annotations of the parent.

For example, a nested message can have a field behavior of REQUIRED while the parent field can be OPTIONAL:

message Title {