From 671cf6ec025923ce01e31b42a90be4311c40efdc Mon Sep 17 00:00:00 2001 From: Alex Stephen Date: Fri, 12 Apr 2024 15:38:28 -0700 Subject: [PATCH] change format --- aep/general/0202/aep.md.j2 | 72 ++++---------------------------------- 1 file changed, 6 insertions(+), 66 deletions(-) diff --git a/aep/general/0202/aep.md.j2 b/aep/general/0202/aep.md.j2 index 716fbe53..982364af 100644 --- a/aep/general/0202/aep.md.j2 +++ b/aep/general/0202/aep.md.j2 @@ -1,62 +1,13 @@ # Fields -The [`google.api.FieldInfo`][field info proto] type, through its accompanying -extension `google.api.field_info`, enriches a field's schema beyond the basic +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 `google.api.field_info` is only necessary when -explicitly stated in this AEP or another that leverages `google.api.FieldInfo` -information. As such, the guidance herein applies to those scenarios as well. - -### Format - -Fields with a primitive type can still have a specific format. To convey that -type format, the `FieldInfo.Format` enumeration is used via the -`(google.api.field_info).format` extension field. The following guidance conveys -the meaning of and requirements for use of each `FieldInfo.Format` value. - -#### UUID4 - -The `UUID4` format represents a UUID version 4 value as governed by -[RFC 4122][]. It **must** only be used on a field of type `string`. - -Such a value **may** be normalized by the service to entirely lowercase letters. -For example, the value `F47AC10B-58CC-0372-8567-0E02B2C3D479` would be -normalized to `f47ac10b-58cc-0372-8567-0e02b2c3d479`. - -As such, equivalence comparison **must not** be done via primitive text -comparison. Instead, an [RFC 4122][] compliant implementation **must** be used. - -#### IPv4 - -The `IPV4` format represents an IP v4 address as governed by [RFC 791][]. It -**must** only be used on a field of type `string`. - -Such a value **may** be condensed by the service, with leading zeros in each -octet stripped. For example, `001.022.233.040` would be condensed to -`1.22.233.40`. - -As such, equivalence comparison **must not** be done via primitive text -comparison. Instead, an [RFC 791][] compliant implementation **must** be used. - -#### IPv6 - -The `IPV6` format represents an IP v6 address as governed by [RFC 4291][]. It -**must** only be used on a field of type `string`. - -Such a value **may** be normalized by the service to entirely lowercase letters -with zeros compressed, following [RFC 5952][]. For example, the value -`2001:0DB8:0::0` would be normalized to `2001:db8::`. - -As such, equivalence comparison **must not** be done via primitive text -comparison. Instead, an [RFC 4291][] compliant implementation **must** be used. - -#### IPv4 or IPv6 - -The `IPV4_OR_IPV6` value indicates that the field can be either an IP v4 or v6 -address, as described in the [IPv4](#ipv4) and [IPv6](#ipv6) sections. +Decorating a field with `buf.validate.field` is only necessary when a field +consistently follows a set pattern. #### Format Compatibility @@ -67,11 +18,6 @@ being specified. Changing an existing format specifier to a different one in all cases **is not** backwards compatible. -#### Extending Format - -Any new `FieldInfo.Format` value **must** be governed by an -[IETF-approved RFC][ietf rfc] or a [Google-approved AEP](./0001.md). - ## Rationale #### Why add a format specifier? @@ -100,13 +46,7 @@ create a user-friendly surface. 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 `FieldInfo.Format` +the format specification is not the responsibility of the `buf.validate.field` enumeration itself. -[field info proto]: https://github.com/googleapis/googleapis/blob/master/google/api/field_info.proto -[rfc 4122]: https://datatracker.ietf.org/doc/html/rfc4122 -[rfc 791]: https://datatracker.ietf.org/doc/html/rfc791 -[rfc 4291]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.2 -[rfc 5952]: https://datatracker.ietf.org/doc/html/rfc5952 -[ietf rfc]: https://www.ietf.org/standards/rfcs -[java uuid]: https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html \ No newline at end of file +[protovalidate]: https://github.com/bufbuild/protovalidate/tree/main/proto/protovalidate \ No newline at end of file