@@ -78,10 +78,36 @@ enum BookView {
7878
7979### Read masks as a request field
8080
81- ** Warning:** Read masks as a single field on the request message, for example: ` google.protobuf.FieldMask read_mask ` are ** DEPRECATED** .
81+ ** Warning:** Read mask as a single, explicit field on the request message is
82+ ** DEPRECATED** for Google APIs. The [ system parameter] ( #field-masks-parameter )
83+ ** must** be used instead. The following guidance is for the benefit of existing
84+ legacy Google and external non-Google usage.
85+
86+ An API ** may** support read masks as a single field on the request message:
87+ ` google.protobuf.FieldMask read_mask ` .
88+
89+ - The read mask ** must** be a ` google.protobuf.FieldMask ` and ** should** be
90+ named ` read_mask ` .
91+ - The field mask ** should** be optional:
92+ - An explicit value of ` "*" ` ** should** be supported, and ** must** return all
93+ fields.
94+ - If the field mask parameter is not provided, all fields ** must** be
95+ returned.
96+ - An API ** may** allow read masks with non-terminal repeated fields (unlike
97+ update masks), but is not obligated to do so.
98+
99+ ## Rationale
100+
101+ ### Deprecating ` read_mask ` in request messages
102+
103+ As mentioned, Google API infrastructure implements a service-wide response
104+ field filtering mechanism, so there is no need for individual API methods to
105+ specify a ` read_mask ` in their request schema. Doing so is both redundant and a
106+ potential point of conflict for the client or service.
82107
83108## Changelog
84109
110+ - ** 2025-06-16** : Reinstate read mask guidance as historical/external reference.
85111- ** 2023-05-09** : Fix top-level enum example and link to AIP-126.
86112- ** 2022-03-14:** Updated guidance on default value and how to specify a read mask.
87113- ** 2021-10-06:** Updated the guidance with system parameters.
0 commit comments