Skip to content

Commit

Permalink
change format
Browse files Browse the repository at this point in the history
  • Loading branch information
rambleraptor committed Apr 12, 2024
1 parent 20c5dce commit 671cf6e
Showing 1 changed file with 6 additions and 66 deletions.
72 changes: 6 additions & 66 deletions aep/general/0202/aep.md.j2
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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?
Expand Down Expand Up @@ -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
[protovalidate]: https://github.com/bufbuild/protovalidate/tree/main/proto/protovalidate

0 comments on commit 671cf6e

Please sign in to comment.