feat(AIP-203): require field behavior (#1100)

To reduce the likelihood of missed field behavior annotations,
require it for all message feilds.

further rationale is explained in the change of AIP-203.

Author: toumorokoshi

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.