feat(AIP-203): clarify immutable optional, required fields (#1120)

Previous guidance had OPTIONAL as a singular value that
had to be mutually exclusive with every other annotation. This
eliminates the ability to express fine-grained details like
OPTIONAL + INPUT_ONLY.

In a similar vain, IMMUTABLE does not imply required, nor input.

Clarifying which annotations are required based on these update.

Author: toumorokoshi

aip/general/0203.md

@@ -24,10 +24,12 @@ field behavior, such as a field being required or immutable.
 RecognitionAudio audio = 2 [(google.api.field_behavior) = REQUIRED];
 ```
 
-- APIs **must** apply the `google.api.field_behavior` annotation on every field.
+- APIs **must** apply the `google.api.field_behavior` annotation on every field
+  on a message or sub-message used in a request.
 - 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
@@ -79,6 +81,14 @@ 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 `true`.
 
+### Optional
+
+The use of `OPTIONAL` indicates that a field is not required.
+
+A field **may** be described as optional if 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.
+
 ### Output only
 
 The use of `OUTPUT_ONLY` indicates that the field is provided in responses, but
@@ -122,13 +132,9 @@ before use.
 
 ### Immutable
 
-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
-ending in `Request`), or a field of a message included within a request
-message.
+The use of `IMMUTABLE` indicates that a field on a resource cannot be changed
+after it's creation. This can apply to either fields that are input or outputs,
+required or optional.
 
 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
@@ -142,20 +148,6 @@ Potential use cases for immutable fields (this is not an exhaustive list) are:
 **Note:** Fields which are "conditionally immutable" **must not** be given the
 immutable annotation.
 
-### Optional
-
-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.
-
 ### Unordered List
 
 The use of `UNORDERED_LIST` on a repeated field of a resource indicates that
@@ -171,6 +163,15 @@ A resource with an unordered list **may** return the list in a stable order, or
 
 ## Rationale
 
+### Required set of annotations
+
+A field used in a request message must be either an input or an output.
+
+In the case of an output, the `OUTPUT_ONLY` annotation is sufficient.
+
+In the case of an input, a field is either required or optional, and therefore
+should have at least the `REQUIRED` or `OPTIONAL` annotation, respectively.
+
 ### Requiring field behavior
 
 By including the field behavior annotation for each field, the overall behavior
@@ -203,6 +204,7 @@ surpass the costs to clients and API users of not doing so.
 
 ## Changelog
 
+- **2023-05-24**: Clarify that `IMMUTABLE` does not imply input nor required.
 - **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