fix(AIP-149): differentiate field presence and behavior

aip/general/0149.md

@@ -38,3 +38,29 @@ message Book {
 value and unset most of the time; if an alternative design does not require
 such a distinction, it is usually preferred. In practice, this means `optional`
 **should** only ever be used for integers and floats.
+
+**Important:** Tracking field presence is *not* the same as documenting API
+field behavior as defined in [AIP-203][]. For example, a field labeled with
+`optional` for presence tracking **may** also be annotated as
+`google.api.field_behavior = REQUIRED` if the field must be set. If you only
+want to document the server perceived behavior of a field, read [AIP-203][].
+
+## Rationale
+
+### field behavior and `optional`
+
+The field behavior annotation and `optional` label are not mutually exclusive,
+because they address different problems. The former,
+`google.api.field_behavior`, focuses on communicating the server's perception of
+a field within the API e.g. if it is required or not, if it is immutable, etc.
+The latter, proto3's `optional`, is a wire format and code generation option
+that is strictly for toggling field presence tracking. While it might be
+confusing for a field to be simultaneously annotated with
+`google.api.field_behavior = REQUIRED` and labeled as `optional`, they are
+unrelated in practice and can reasonably be used together.
+
+## Changelog
+
+- **2023-06-20**: Differentiate from field behavior documentation
+
+[AIP-203]: ./0203.md