AIP-202

Fields

The google.api.FieldInfo type, through its accompanying extension google.api.field_info, 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 AIP 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 and 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 FieldInfo.Format value must be governed by an IETF-approved RFC or a Google-approved AIP.

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. 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 FieldInfo.Format enumeration itself.