Skip to content

Commit c2c6b11

Browse files
authored
fix(AIP-157): reinstate read mask as historical guidance (#1529)
1 parent 90ab3ab commit c2c6b11

1 file changed

Lines changed: 27 additions & 1 deletion

File tree

aip/general/0157.md

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)