[AIP-129, AIP-213] Resolve conflicting guidance on normalizing client-owned fields of common types with inherent normalization semantics

[PeytonT]

AIP-213, AIP-129, and AIP-202 form a conflict.

AIP-213 says to use common types, and the common type google.type.Decimal has documented mandatory normalization semantics.

  // Services **should** normalize decimal values before storing them by:
  //
  //   - Removing an explicitly-provided `+` sign (`+2.5` -> `2.5`).
  //   - Replacing a zero-length integer value with `0` (`.5` -> `0.5`).
  //   - Coercing the exponent character to lower-case (`2.5E8` -> `2.5e8`).
  //   - Removing an explicitly-provided zero exponent (`2.5e0` -> `2.5`).
  //
  // Services **may** perform additional normalization based on its own needs
  // and the internal decimal implementation selected, such as shifting the
  // decimal point and exponent value together (example: `2.5e-1` <-> `0.25`).
  // Additionally, services **may** preserve trailing zeroes in the fraction
  // to indicate increased precision, but are not required to do so.
  //
  // Note that only the `.` character is supported to divide the integer
  // and the fraction; `,` **should not** be supported regardless of locale.
  // Additionally, thousand separators **should not** be supported. If a
  // service does support them, values **must** be normalized.

However, AIP-129 has a mandatory prohibition on normalizing any field unless it is a string field with an AIP-202 FieldInfo Format annotation.

User-Specified Fields

For user-specified fields, the value in response from the service must be the same as provided by the create or update request. For string fields this means returning the value unchanged, with one exception:

When a string field has a data type annotation, a normalized string that represents the given value may be returned.

Normalizations

A field that is normalized by the service must be annotated with the google.api.field_info extension. See (AIP-202) for guidance on using this extension The allowed set of normalizations includes the following formats:

• uuid
• ipv4
• ipv6
• email

google.type.Decimal is not a string field, and although it is a wrapper around a string value, value is not annotated with a google.api.FieldInfo data type annotation, and even if it were to be so-annotated, none of the existing format variants are appropriate.

Conceivably this could be addressed by adding a new FieldInfo.Format variant for google.type.Decimal and applying it either to google.type.Decimal.value or requiring APIs to annotate fields of type google.type.Decimal, but this conflicts with guidance in AIP-202 governing introduction of new FieldInfo.Format variants.

Any new FieldInfo.Format value must be governed by an IETF-approved RFC or a Google-approved AIP.

It is possible to construe the format of google.type.Decimal.value as being "governed by... a Google-approved AIP" since it is an AIP-213 common type, but this is clearly against the intention of AIP-202 because the normalization semantics of google.type.Decimal are subject to significant discretion by the implementing service.

---

The AIP-129 guidance is broader than it should be. The semantics of AIP-213 common types are essentially AIPs in their own right, and should be blanket exempted from the guidance in AIP-129.