vulns.co
/
GKData.io MCP and API Buy me a coffee

Google

Google API field masks: preserve server-owned and immutable state

Google's approved field-mask guidance defines which fields an update selects, while separate field rules determine what may change. Services must ignore output-only input even when a containing field is selected; the supporting guidance says to ignore unchanged immutable values and return INVALID_ARGUMENT for attempted changes. These annotations describe required behavior but do not perform validation themselves.

Open the referenceImplementation GuideReviewed 2026-10-04

How to use this reference

Editorial synthesis: document separately what the caller is allowed to change, which fields the request selects and the server's rules for changing each field. Selecting a valid field does not grant permission to modify it. Enforce each nested field's own rules, regardless of its parent's annotation. Use dedicated operations for business-state changes when the API contract requires them, rather than a generic update.

Before reading

  • Basic familiarity with resource-oriented APIs, partial updates and access-control modeling

Context and limits

  • AIP-161's Created and Updated headers both show 2021-03-01. Its displayed output-only changelog date is 2023-10-18, while the corresponding first-party commit is timestamped 2023-10-19T15:57:39Z. A later 2025-03-28 commit added an AIP-157 link; neither header nor newest displayed changelog establishes the last source revision.
  • AIP-203's headers show 2018-07-17 and its newest displayed changelog entry is 2023-09-14, although a reviewed 2026-06-25 commit adds an optional-field clarification. AIP-134's headers show 2019-01-24 while its newest displayed changelog entry is 2025-10-03. These dates are not interchangeable publication or edition dates.
  • AIP-203 forbids an error merely because output-only input is present and requires it to be cleared or ignored. This differs from immutable input, for which unchanged values should be ignored and changes should cause a validation error. Nested field behavior is independent of its parent's annotation.
  • AIP-134 says generic updates should avoid side effects and state fields must not be directly writable through them. The separation of field selection from caller authorization is editorial synthesis; these AIPs' explicit rules concern field behavior and update semantics.
  • These are Google API design requirements, not universal protocol guarantees or proof that a particular service enforces them. This resource establishes no incident, affected deployment, bounty, exploitability or testing authorization.

Sources

  1. AIP-161: Field masksGoogle · reviewed 2026-10-04
  2. AIP-203: Field behavior documentationGoogle · reviewed 2026-10-04
  3. AIP-134: Standard methods: UpdateGoogle · reviewed 2026-10-04
  4. AIP-161/AIP-203: converge output-only update-mask guidanceGoogle AIP maintainers · reviewed 2026-10-04
  5. AIP-161: link to AIP-157Google AIP maintainers · reviewed 2026-10-04
  6. AIP-203: clarify optional field presence and field behaviorGoogle AIP maintainers · reviewed 2026-10-04

Record reviewed 2026-10-04. Snapshot af2809c308fc. Open the complete JSON contract.

Library synced 2026-11-18 · cases last reviewed 2026-10-05

af2809c308fc · JSON exports & schemas · CC BY 4.0 content / MIT software