Skip to content

Commit 20c5dce

Browse files
rambleraptorrambleraptor
committed
adopt AEP-202
1 parent 1625d93 commit 20c5dce

File tree

2 files changed

+119
-0
lines changed

2 files changed

+119
-0
lines changed

‎aep/general/0202/aep.md.j2

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Fields
2+
3+
The [`google.api.FieldInfo`][field info proto] type, through its accompanying
4+
extension `google.api.field_info`, enriches a field's schema beyond the basic
5+
name and type information.
6+
7+
## Guidance
8+
9+
Decorating a field with `google.api.field_info` is only necessary when
10+
explicitly stated in this AEP or another that leverages `google.api.FieldInfo`
11+
information. As such, the guidance herein applies to those scenarios as well.
12+
13+
### Format
14+
15+
Fields with a primitive type can still have a specific format. To convey that
16+
type format, the `FieldInfo.Format` enumeration is used via the
17+
`(google.api.field_info).format` extension field. The following guidance conveys
18+
the meaning of and requirements for use of each `FieldInfo.Format` value.
19+
20+
#### UUID4
21+
22+
The `UUID4` format represents a UUID version 4 value as governed by
23+
[RFC 4122][]. It **must** only be used on a field of type `string`.
24+
25+
Such a value **may** be normalized by the service to entirely lowercase letters.
26+
For example, the value `F47AC10B-58CC-0372-8567-0E02B2C3D479` would be
27+
normalized to `f47ac10b-58cc-0372-8567-0e02b2c3d479`.
28+
29+
As such, equivalence comparison **must not** be done via primitive text
30+
comparison. Instead, an [RFC 4122][] compliant implementation **must** be used.
31+
32+
#### IPv4
33+
34+
The `IPV4` format represents an IP v4 address as governed by [RFC 791][]. It
35+
**must** only be used on a field of type `string`.
36+
37+
Such a value **may** be condensed by the service, with leading zeros in each
38+
octet stripped. For example, `001.022.233.040` would be condensed to
39+
`1.22.233.40`.
40+
41+
As such, equivalence comparison **must not** be done via primitive text
42+
comparison. Instead, an [RFC 791][] compliant implementation **must** be used.
43+
44+
#### IPv6
45+
46+
The `IPV6` format represents an IP v6 address as governed by [RFC 4291][]. It
47+
**must** only be used on a field of type `string`.
48+
49+
Such a value **may** be normalized by the service to entirely lowercase letters
50+
with zeros compressed, following [RFC 5952][]. For example, the value
51+
`2001:0DB8:0::0` would be normalized to `2001:db8::`.
52+
53+
As such, equivalence comparison **must not** be done via primitive text
54+
comparison. Instead, an [RFC 4291][] compliant implementation **must** be used.
55+
56+
#### IPv4 or IPv6
57+
58+
The `IPV4_OR_IPV6` value indicates that the field can be either an IP v4 or v6
59+
address, as described in the [IPv4](#ipv4) and [IPv6](#ipv6) sections.
60+
61+
#### Format Compatibility
62+
63+
Adding a format specifier to an existing, unspecified field **is not** backwards
64+
compatible, *unless* the field in question has always conformed to the format
65+
being specified.
66+
67+
Changing an existing format specifier to a different one in all cases **is not**
68+
backwards compatible.
69+
70+
#### Extending Format
71+
72+
Any new `FieldInfo.Format` value **must** be governed by an
73+
[IETF-approved RFC][ietf rfc] or a [Google-approved AEP](./0001.md).
74+
75+
## Rationale
76+
77+
#### Why add a format specifier?
78+
79+
The format of a primitive-typed field can be critical to its usability. Some
80+
programming languages may convey a specific type format as a standalone type,
81+
as Java does with [UUID][java uuid]. Most have specific structural requirements
82+
that are validated by the service, so conveying the format to the user ahead of
83+
time is critical to their experience.
84+
85+
#### Why discourage primitive equality comparisons?
86+
87+
The text representations of the supported formats have many nuances and
88+
transforming the value into a canonical representation is non-trivial. As such,
89+
aligning implementations between each consumer and each service without any
90+
issue is infeasiable.
91+
92+
#### Why document value normalizations?
93+
94+
While primitive comparison is not recommended for any of the supported formats,
95+
uniform normalization of values is important to set consumer expectations, and
96+
create a user-friendly surface.
97+
98+
#### Why require an RFC or AEP for new formats?
99+
100+
Those formats which are sufficiently standardized to merit an RFC or AEP are
101+
stable enough and widely enough known to be incorporated as a supported value
102+
and see usage in Google APIs. Requiring such extra guidance means that governing
103+
the format specification is not the responsibility of the `FieldInfo.Format`
104+
enumeration itself.
105+
106+
[field info proto]: https://github.com/googleapis/googleapis/blob/master/google/api/field_info.proto
107+
[rfc 4122]: https://datatracker.ietf.org/doc/html/rfc4122
108+
[rfc 791]: https://datatracker.ietf.org/doc/html/rfc791
109+
[rfc 4291]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.2
110+
[rfc 5952]: https://datatracker.ietf.org/doc/html/rfc5952
111+
[ietf rfc]: https://www.ietf.org/standards/rfcs
112+
[java uuid]: https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html

‎aep/general/0202/aep.yaml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
id: 202
3+
state: reviewing
4+
slug: fields
5+
created: 2023-01-22
6+
placement:
7+
category: fields

0 commit comments

Comments
 (0)