feat: align FieldMask features with standard Protocol Buffer libraries

aip/general/0127.md

@@ -94,6 +94,14 @@ message CreateBookRequest {
   - The `body` **must not** be a `repeated` field.
   - Fields **should not** use the `json_name` annotation to alter the field
     name in JSON, unless doing so for backwards-compatibility reasons.
+- Request fields that are not bound to the URL path or the HTTP `body` are
+  passed as URL query parameters.
+
+**Note:** For the detailed transcoding behavior for the entire request
+(including how fields are bound across the URL path, HTTP request body, and URL
+query parameters), refer to the [`google.api.http`][http-proto] documentation.
+For information on how fields and types are encoded—including query parameters
+and well-known types—refer to the Protocol Buffers canonical [JSON encoding][].
 
 **Note:** Bi-directional streaming RPCs should not include a `google.api.http`
 annotation at all. If feasible, the service **should** provide non-streaming
@@ -129,6 +137,9 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
 
 ## Changelog
 
+- **2026-10-14**: Added general note referencing `google.api.http` transcoding
+  documentation and Protocol Buffers JSON encoding for request fields and
+  well-known types.
 - **2022-08-18**: Added the comment that query string parameter names are
   in camelCase.
 - **2021-01-06**: Added clarification around `body` and nested fields.
@@ -144,6 +155,7 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
 [aip-134]: ./0134.md
 [aip-135]: ./0135.md
 [aip-136]: ./0136.md
+[http-proto]: https://github.com/googleapis/googleapis/blob/master/google/api/http.proto
 [json encoding]: https://developers.google.com/protocol-buffers/docs/proto3#json
 [rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
 <!-- prettier-ignore-end -->

aip/general/0134.md

@@ -104,8 +104,17 @@ message UpdateBookRequest {
   - The field **must** be optional, and the service **must** treat an omitted
     field mask as an implied field mask equivalent to all fields that are
     populated (have a non-empty value).
+  - If an `update_mask` is provided but is empty (i.e. contains no paths:
+    `paths: []`), the service **should** treat the request as a no-op and
+    return the existing resource unmodified.
   - Update masks **must** support a special value `*`, meaning full replacement
     (the equivalent of `PUT`).
+    - The wildcard value `*` is an API-level convention. Standard Protocol
+      Buffer runtime libraries validate mask paths directly against message
+      definitions and do not recognize `*` as a valid field path.
+    - Services supporting `*` are responsible for handling full replacement
+      directly in their service implementation, rather than relying on standard
+      Protocol Buffer field mask helper utilities.
     - API producers need to be conscious of how adding new, mutable fields to a
       resource will be handled when consumers use `*` without knowledge of said
       new, mutable fields. Likewise consumers need to use `*` only when the
@@ -304,6 +313,9 @@ does not exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 
 ## Changelog
 
+- **2026-10-08**: Clarify that wildcard `*` update mask is an API convention
+  for full replacement that is not supported by standard Protocol Buffer
+  runtime libraries.
 - **2025-10-03**: Allow use of partial responses via AIP-157.
 - **2024-12-03**: Add caveats to usage of full replacement `update_mask`.
 - **2024-03-14**: Make `update_mask` optional field_behaviour guidance a **must**.

aip/general/0157.md

@@ -14,32 +14,15 @@ needs to give the user control over which fields it sends back.
 
 ## Guidance
 
-APIs **may** support partial responses in one of two ways:
-
-### Field masks parameter
-
-Field masks (`google.protobuf.FieldMask`) can be used for granting the user
-fine-grained control over what fields are returned. An API **should** support the mask in a side channel.
-For example, the parameter can be specified either using an HTTP query
-parameter, an HTTP header, or a [gRPC metadata entry][1]. Google Cloud APIs specify field masks as a [system parameter][0].
-
-Field masks **should not** be specified in the [request](./0157.md#read-masks-as-a-request-field).
-
-- The value of the field mask parameter **must** be a `google.protobuf.FieldMask`.
-- The field mask parameter **must** be optional:
-  - An explicit value of `"*"` **should** be supported, and **must** return all
-    fields.
-  - If the field mask parameter is omitted, it **must** default to `"*"`, unless otherwise documented.
-- An API **may** allow read masks with non-terminal repeated fields (unlike
-  update masks), but is not obligated to do so.
-
-**Note:** Changing the default value of the field mask parameter is a [breaking change](../0180.md#semantic-changes).
+APIs **may** support partial responses. When partial responses are needed, APIs
+**should** use view enumerations as the primary pattern. Alternatively, an API
+**may** support partial responses via infrastructure-level field mask parameters.
 
 ### View enumeration
 
-Alternatively, an API **may** support partial responses with view enums.
-View enums are useful for situations where an API only wants to expose a small
-number of permutations to the user:
+APIs **should** support partial responses with view enums.
+View enums are useful for situations where an API wants to expose a small
+number of predictable permutations to the user:
 
 ```proto
 enum BookView {
@@ -86,6 +69,35 @@ enum BookView {
   request the full resource be populated in the response, like this View
   pattern, is preferred if partial responses are deemed necessary.
 
+### Field masks parameter
+
+Alternatively, an API **may** support partial responses using field masks
+(`google.protobuf.FieldMask`) for granting the user fine-grained control over
+what fields are returned. An API **should** support the mask in a side channel.
+For example, the parameter can be specified either using an HTTP query
+parameter, an HTTP header, or a [gRPC metadata entry][1]. Google Cloud APIs
+specify field masks as a [system parameter][0].
+
+Field masks **should not** be specified in the [request](./0157.md#read-masks-as-a-request-field).
+
+- The value of the field mask parameter **must** be a `google.protobuf.FieldMask`.
+- The field mask parameter **must** be optional:
+  - If the field mask parameter is omitted, it **must** return all fields (or
+    the default view documented for the method).
+  - API infrastructure or intermediary proxies may support wildcard values
+    such as `*` to indicate all fields. However, standard Protocol Buffer
+    runtime libraries do not recognize `*` as a valid field path.
+  - Services implementing partial response filtering should be aware that
+    intermediary infrastructure may normalize, transform, or omit mask paths
+    before they reach the service. An empty field mask should generally be
+    treated as requesting all fields (or the default view).
+- APIs are discouraged from supporting non-terminal repeated fields (e.g.
+  `authors.*.given_name`) in read masks, as standard Protocol Buffer runtime
+  libraries do not support traversing beyond repeated fields (see
+  [AIP-161](./0161.md#non-standard-extensions)).
+
+**Note:** Changing the default value of the field mask parameter is a [breaking change](../0180.md#semantic-changes).
+
 ### Read masks as a request field
 
 **Warning:** Read mask as a single, explicit field on the request message is
@@ -99,12 +111,9 @@ An API **may** support read masks as a single field on the request message:
 - The read mask **must** be a `google.protobuf.FieldMask` and **should** be
   named `read_mask`.
 - The field mask **should** be optional:
-  - An explicit value of `"*"` **should** be supported, and **must** return all
-    fields.
-  - If the field mask parameter is not provided, all fields **must** be
-    returned.
-- An API **may** allow read masks with non-terminal repeated fields (unlike
-  update masks), but is not obligated to do so.
+  - If the field mask is not provided, all fields **must** be returned.
+- Standard Protocol Buffer runtime libraries do not support wildcards (`*`) or
+  non-terminal repeated fields in field masks.
 
 ## Rationale
 
@@ -117,6 +126,9 @@ potential point of conflict for the client or service.
 
 ## Changelog
 
+- **2026-10-08**: Elevate View enumeration to the primary recommendation for
+  partial responses; clarify standard Protocol Buffer library behavior for
+  field masks.
 - **2025-10-03**: Added default view guidance for other RPC types, and
                   declarative client warning.
 - **2025-06-16**: Reinstate read mask guidance as historical/external reference.

aip/general/0161.md

@@ -72,70 +72,23 @@ when resources contain messages (example: `author.given_name`).
 **Note:** A user **must** be able to specify either a field as a whole, or one
 of its subfields: `author` and `author.given_name` are both valid.
 
-### Map fields
-
-Field masks **may** permit the specification of specific fields in a map, if
-and only if the map's keys are either strings or integers, using the `.`
-character for traversal.
-
-Field masks **should** support string keys that contain characters that are
-problematic for the field mask syntax, using the backtick character.
-
-```proto
-message Book {
-  // The name of the book.
-  // Format: publishers/{publisher}/books/{book}
-  string name = 1;
-
-  // Reviews for the back cover. The key is the author of the review,
-  // and the value is the text of the review.
-  //
-  // Valid field masks: reviews, reviews.smith, reviews.`John Smith`
-  map<string, string> reviews = 2;
-}
-```
-
-### Wildcards
-
-Field masks **may** permit the use of the `*` character on a repeated field or
-map to indicate the specification of particular sub-fields in the collection:
+### Repeated fields
 
-```proto
-message Book {
-  option (google.api.resource) = {
-    type: "library.googleapis.com/Book"
-    pattern: "publishers/{publisher}/books/{book}"
-  };
-
-  // The name of the book.
-  // Format: publishers/{publisher}/books/{book}
-  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+Field masks **must** permit specifying a repeated field as a whole (example:
+`authors`).
 
-  // The author or authors of the book.
-  // Valid field masks: authors, authors.*.given_name, authors.*.family_name
-  // Invalid field masks: authors.0, authors.0.given_name
-  repeated Author authors = 2;
-}
-
-message Author {
-  // The author's given name.
-  string given_name = 1;
-
-  // The author's family name.
-  string family_name = 2;
-}
-```
-
-**Note:** Field masks **must not** permit accessing a particular element of a
-repeated field by index, and **must** return an `INVALID_ARGUMENT` error if
-this is attempted.
+In standard Protocol Buffer runtime libraries, repeated fields are **only**
+permitted as the terminal (leaf) element of a path. Field masks **must not**
+permit accessing a particular element of a repeated field by index (example:
+`authors.0`), and **must** return an `INVALID_ARGUMENT` error if this is
+attempted.
 
 ### Output only fields
 
-If a user includes an output only field in an update mask indirectly (by using
-a wildcard or specifying an overall message that includes an output-only
-subfield), the service **must** ignore any output only fields provided as
-input, even if they are cleared or modified.
+If a user includes an output only field in an update mask indirectly (by
+specifying an overall message that includes an output-only subfield), the
+service **must** ignore any output only fields provided as input, even if they
+are cleared or modified.
 
 If a user directly specifies an output only field in an update mask, the
 service **must** ignore the output only fields provided as input, even if
@@ -145,15 +98,47 @@ input and output.
 ### Invalid field mask entries
 
 When reading data, field masks **may** ignore entries that point to a value
-that can not exist (either a field that does not exist, or a map key that the
-service considers invalid).
+that can not exist (such as a field name that does not exist in the schema).
 
 When writing data, field masks **should** return an `INVALID_ARGUMENT` error if
 an entry points to a value that can not exist; however, the service **may**
 permit deletions.
 
+## Non-standard extensions
+
+The following features have occasionally appeared in API designs or custom
+infrastructure, but are **not supported** by standard Protocol Buffer runtime
+libraries. Standard Protocol Buffer utilities validate paths directly against
+message definitions and do not support traversing maps or collections.
+
+Services that choose to support these extensions are responsible for providing
+custom parsing and processing logic:
+
+### Map fields
+
+Standard Protocol Buffer serialization treats maps as repeated message
+entries, and standard runtime utilities do not support traversing into map
+entries.
+
+Services **may** support field mask paths targeting specific map entries using
+the `.` character for traversal (e.g. `reviews.smith`), or backtick escaping for
+keys containing special characters (e.g. `` reviews.`John Smith` ``).
+
+### Collection wildcards
+
+Standard Protocol Buffer runtime utilities require repeated fields to be
+terminal elements in a path. Services **may** support wildcards (e.g. `*`) on
+repeated fields or maps (e.g. `authors.*.given_name`) to specify sub-fields
+across elements in a collection.
+
+(Note: For the top-level wildcard `*` used for full replacement in standard
+Update methods, see [AIP-134](./0134.md#request-message)).
+
 ## Changelog
 
+- **2026-10-08**: Clarify support limits of standard Protocol Buffer libraries;
+  move map key traversal and mid-path collection wildcards to non-standard
+  extensions.
 - **2023-10-18**: Update guidance for presence of output only fields in update
   mask.
 - **2023-07-17**: Move `update_mask` guidance to AIP-134.