diff --git a/aip/general/0157.md b/aip/general/0157.md index fb9066a0bc..aa52f3ac51 100644 --- a/aip/general/0157.md +++ b/aip/general/0157.md @@ -78,10 +78,36 @@ enum BookView { ### Read masks as a request field -**Warning:** Read masks as a single field on the request message, for example: `google.protobuf.FieldMask read_mask` are **DEPRECATED**. +**Warning:** Read mask as a single, explicit field on the request message is +**DEPRECATED** for Google APIs. The [system parameter](#field-masks-parameter) +**must** be used instead. The following guidance is for the benefit of existing +legacy Google and external non-Google usage. + +An API **may** support read masks as a single field on the request message: +`google.protobuf.FieldMask read_mask`. + +- 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. + +## Rationale + +### Deprecating `read_mask` in request messages + +As mentioned, Google API infrastructure implements a service-wide response +field filtering mechanism, so there is no need for individual API methods to +specify a `read_mask` in their request schema. Doing so is both redundant and a +potential point of conflict for the client or service. ## Changelog +- **2025-06-16**: Reinstate read mask guidance as historical/external reference. - **2023-05-09**: Fix top-level enum example and link to AIP-126. - **2022-03-14:** Updated guidance on default value and how to specify a read mask. - **2021-10-06:** Updated the guidance with system parameters.