Skip to content

Commit aa87b24

Browse files
noahdietznoahdietz
authored
feat(AIP-202): add enriched Field descriptor AIP (#1216)
1 parent 22fc686 commit aa87b24

1 file changed

Lines changed: 120 additions & 0 deletions

File tree

‎aip/general/0202.md‎

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

0 commit comments

Comments
 (0)