Adopt AEP-202: Fields

aep/general/0202/aep.md.j2

@@ -0,0 +1,52 @@
+# Fields
+
+The [`buf.validate.field`][protovalidate] type, through its accompanying
+extension `buf.validate.field`, enriches a field's schema beyond the basic
+name and type information.
+
+## Guidance
+
+Decorating a field with `buf.validate.field` is only necessary when a field
+consistently follows a set pattern.
+
+#### Format Compatibility
+
+Adding a format specifier to an existing, unspecified field **is not** backwards
+compatible, *unless* the field in question has always conformed to the format
+being specified.
+
+Changing an existing format specifier to a different one in all cases **is not**
+backwards compatible.
+
+## Rationale
+
+#### Why add a format specifier?
+
+The format of a primitive-typed field can be critical to its usability. Some
+programming languages may convey a specific type format as a standalone type,
+as Java does with [UUID][java uuid]. Most have specific structural requirements
+that are validated by the service, so conveying the format to the user ahead of
+time is critical to their experience.
+
+#### Why discourage primitive equality comparisons?
+
+The text representations of the supported formats have many nuances and
+transforming the value into a canonical representation is non-trivial. As such,
+aligning implementations between each consumer and each service without any
+issue is infeasiable.
+
+#### Why document value normalizations?
+
+While primitive comparison is not recommended for any of the supported formats,
+uniform normalization of values is important to set consumer expectations, and
+create a user-friendly surface.
+
+#### Why require an RFC or AEP for new formats?
+
+Those formats which are sufficiently standardized to merit an RFC or AEP are
+stable enough and widely enough known to be incorporated as a supported value
+and see usage in Google APIs. Requiring such extra guidance means that governing
+the format specification is not the responsibility of the `buf.validate.field`
+enumeration itself.
+
+[protovalidate]: https://github.com/bufbuild/protovalidate/tree/main/proto/protovalidate

aep/general/0202/aep.yaml

@@ -0,0 +1,7 @@
+---
+id: 202
+state: reviewing
+slug: fields
+created: 2023-01-22
+placement:
+  category: protobuf