[noahdietz]

Summary

Clarify support boundaries for google.protobuf.FieldMask across AIP-134, AIP-157, and AIP-161 to align with standard Protocol Buffer runtime library capabilities. Also clarify HTTP transcoding and query parameter encoding behavior in AIP-127.

Changes

• AIP-127 (HTTP and gRPC Transcoding):
  • Add general note referencing google.api.http documentation for detailed request transcoding behavior across path, body, and query parameters.
  • Reference Protocol Buffers canonical JSON encoding for how request fields and types are encoded, especially well-known types (such as FieldMask).
  • Explicitly document that request fields not bound to the URL path or body are passed as URL query parameters.
• AIP-134 (Standard Update):
  • Retain the requirement that standard update methods must support * for full resource replacement (the equivalent of PUT).
  • Document that * is an API-level convention that is not recognized by standard Protocol Buffer runtime libraries.
  • Note that services supporting * are responsible for handling full replacement directly in their service implementation, rather than relying on standard Protocol Buffer field mask helper utilities.
  • Clarify that an empty update_mask (paths: []) should be treated as a no-op returning the existing resource unmodified.
• AIP-157 (Partial Responses):
  • Invert structure to make View enumeration the primary recommended pattern for partial responses.
  • Clarify that wildcard * in field mask parameters is an infrastructure-level convention not supported by standard Protocol Buffer runtime libraries.
  • Note that intermediary proxies may normalize or omit mask paths, and that services should generally treat empty read masks as requesting all fields (or the default view).
  • Discourage non-terminal repeated fields in read masks.
• AIP-161 (Field Masks):
  • Clarify that standard Protocol Buffer runtime libraries validate paths directly against message definitions and require repeated fields to be terminal in a path.
  • Move non-canonical features (map key traversal with dot notation / backticks and mid-path collection wildcards) to a dedicated "Non-standard extensions" section, noting that standard runtime libraries do not support them.

Internal tracking bug http://b/562618985