feat(AIP-203): require field behavior

aip/general/0203.md

@@ -16,18 +16,19 @@ 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's 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** use the `google.api.field_behavior` annotation on every message
+field and have one of [`REQUIRED`][], [`OPTIONAL`][], or [`OUTPUT_ONLY`][].
+
+Fields with no annotation are interpreted as `OPTIONAL` for
+backwards-compatility, but 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
@@ -162,11 +163,36 @@ 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
+
+The field behavior annotation explicitly states the intended behavior of the
+resource which enables better documentation. In addition, requiring the
+annotation forces the API author to explicitly consider the behavior during
+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 the require property for an [IaC][] client.
+
+## History
+
+In 2023-05, field behavior was made mandatory due to required and immutable
+field behavior annotations being missed often, resulting in poor quality
+clients that had to deal with backward-incompatible changes.
+
+The cost of clients and API users addressing breaking changes outweighed the
+cost of a one-line annotation per field during API authoring.
+
 [aip-133]: ./0133.md
 [aip-134]: ./0134.md
+[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.