From aa87b2450d813157a0ee359ee32caf76976049dd Mon Sep 17 00:00:00 2001 From: Noah Dietz Date: Fri, 22 Sep 2023 09:42:18 -0700 Subject: [PATCH] feat(AIP-202): add enriched Field descriptor AIP (#1216) --- aip/general/0202.md | 120 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 aip/general/0202.md diff --git a/aip/general/0202.md b/aip/general/0202.md new file mode 100644 index 0000000000..a53308bf3d --- /dev/null +++ b/aip/general/0202.md @@ -0,0 +1,120 @@ +--- +id: 202 +state: reviewing +created: 2023-09-22 +placement: + category: fields + order: 0 +--- + +# Fields + +The [`google.api.Field`][field proto] type, through its accompanying extension +`google.api.field`, enriches a field's schema beyond the basic name and type +information. + +## Guidance + +Decorating a field with `google.api.field` is only necessary when explicitly +stated in this AIP or another that leverages `google.api.Field` 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 `Field.Format` enumeration is used via the +`(google.api.field).format` extension field. The following guidance conveys the +meaning of and requirements for use of each `Field.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, +and zero-padded partial and empty octets. For example, the value `2001:DB8::` +would be normalized to `2001:0db8:0:0`. + +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. + +#### 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. + +#### Extending Format + +Any new `Field.Format` value **must** be governed by an +[IETF-approved RFC][ietf rfc] or a [Google-approved AIP](./0001.md). + +## 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 AIP for new formats? + +Those formats which are sufficiently standardized to merit an RFC or AIP 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 `Field.Format` +enumeration itself. + +[field proto]: https://github.com/googleapis/googleapis/blob/master/google/api/field.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 +[ietf rfc]: https://www.ietf.org/standards/rfcs +[java uuid]: https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html