diff --git a/aip/general/0157.md b/aip/general/0157.md index fb9066a0bc..69993669a7 100644 --- a/aip/general/0157.md +++ b/aip/general/0157.md @@ -78,11 +78,21 @@ 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 masks as a single field on the request message, for example: `google.protobuf.FieldMask read_mask` are **DEPRECATED**. Users and Google APIs **must** instead consult the `fields` +[system parameter](https://cloud.google.com/apis/docs/system-parameters). + +## Rationale + +### Discontinuing `read_mask` + +Long before the `read_mask` request field was introduced, Google APIs at a +system level supported the same functionality via the system parameter `fields`. +So, `read_mask` as a request field was discontinued to dedupe the functionality. ## Changelog -- **2023-05-09**: Fix top-level enum example and link to AIP-126. +- **2025-05-12:** Add historical rationale for read_mask discontinuation. +- **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. - **2021-03-04:** Added guidance for conflicting view enums.