From 22d34112791ee66dccf5437dd7a1cd8923c34415 Mon Sep 17 00:00:00 2001 From: noahdietz Date: Mon, 16 Jun 2025 12:23:05 -0700 Subject: [PATCH 1/2] fix(AIP-157): reinstate read mask as historical guidance --- aip/general/0157.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/aip/general/0157.md b/aip/general/0157.md index fb9066a0bc..7eaf93c9dc 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 +Google and any 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. From c57420e8c9988af33dd660437aecd6379f4f4325 Mon Sep 17 00:00:00 2001 From: noahdietz Date: Wed, 18 Jun 2025 13:56:07 -0700 Subject: [PATCH 2/2] chore(AIP-157): qualify usage to legacy google usage --- aip/general/0157.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0157.md b/aip/general/0157.md index 7eaf93c9dc..aa52f3ac51 100644 --- a/aip/general/0157.md +++ b/aip/general/0157.md @@ -81,7 +81,7 @@ enum BookView { **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 -Google and any non-Google usage. +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`.