diff --git a/aip/general/0203.md b/aip/general/0203.md index 7178c227b..18a8df942 100644 --- a/aip/general/0203.md +++ b/aip/general/0203.md @@ -16,22 +16,29 @@ behavior (for example, to optimize client library signatures). ## Guidance -APIs **should** use the `google.api.field_behavior` annotation to describe -well-understood field behavior, such as a field's being required, immutable, or -output only: +APIs use the `google.api.field_behavior` annotation to describe well-understood +field behavior, such as a field being required or immutable. ```proto // 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 -optional. +- APIs **must** apply the `google.api.field_behavior` annotation on every field. +- The annotation **must** include any [google.api.FieldBehavior][] values that + accurately describe the behavior of the field. + - `FIELD_BEHAVIOR_UNSPECIFIED` **must not** be used. + +**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 users. +document this behavior for clients. ## Vocabulary @@ -162,11 +169,41 @@ 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. +## Rationale + +### Requiring field behavior + +By including the field behavior annotation for each field, the overall behavior +that the resource exhibits is more clearly defined. Clearly defined field +behavior improves programmatic clients and user understanding. + +Requiring the annotation also forces the API author to explicitly consider the +behavior when initially authoring of the API. + +Modifying field behavior after initial authoring results in +backwards-incompatible changes in clients. For example, making an optional field +required, results in backwards-incompatible changes in the method signature of +an RPC or a resource in an [IaC][] client. + +## History + +In 2023-05 field_behavior was made mandatory. Prior to this change, the +annotation was often omitted. Its values, e.g. REQUIRED, OUTPUT_ONLY, and +IMMUTABLE, are relied upon to produce high quality clients. Further, when the +value is added after the fact or changes, within a major version, it is +backwards-incompatible, which is likely to break clients. + +The benefits of requiring field_behavior, at the time that the API is authored, +surpass the costs to clients and API users of not doing so. + [aip-133]: ./0133.md [aip-134]: ./0134.md +[google.api.FieldBehavior]: https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto#L49 +[IaC]: ./0009.md#iac ## Changelog +- **2023-05-10**: Added guidance to require the annotation. - **2020-12-15**: Added guidance for `UNORDERED_LIST`. - **2020-05-27**: Clarify behavior when receiving an immutable field in an update.