A field mask is a collection of strings identifying which resource fields an API should return or modify. It enables partial retrievals, reduces unnecessary data transfer, and supports fine-grained updates without replacing an entire resource. section 8.2 section 8.6
Use field masks with these defaults and constraints:
- Default GET retrievals to all fields unless the client supplies a mask; explicitly document unusually large or expensive fields excluded from that default. section 8.3.4
- Default PATCH updates to an implicit mask inferred from fields present in the request body, distinguishing an omitted field from an explicit null. section 8.3.5
- Transport masks as repeated query parameters, such as ?fieldMask=title&fieldMask=description; avoid putting them in GET bodies or inside PATCH resource representations. section 8.3.1
- Represent nested paths with dots, nested interfaces with .* when selecting all nested fields, and dynamic map keys with quoted backtick syntax when necessary. section 8.3.2
- Treat invalid fields as existing with an undefined value, and do not use masks to address array elements by position or index. section 8.6
- Use GraphQL instead when clients need relationship-based joins or SQL-like querying across related resources; field masks are intentionally narrower. section 8.4
Updating and removing ChatRoom fields
A typed API can define `type FieldMask = string[]`, then accept it on both get and update requests. `GET /chatRooms/1?fieldMask=title&fieldMask=loggingConfig.maxSizeMb` returns only the selected fields. `PATCH /chatRooms/1` with `{ "description": "New description" }` infers `["description"]`. To remove the `test` key from the dynamic `settings` map rather than set it to null, send `PATCH /chatRooms/1?fieldMask=settings.test` with `{}`. A batch update can accept masks per request and optionally one blanket mask, provided they do not conflict. section 8.3.5 section 8.3.6 section 18.3.9
Listing 8.3 Example of standard get and update requests with field masks included
type FieldMask = string[]; #1
interface GetChatRoomRequest {
id: string;
fieldMask: FieldMask; #2
}
interface UpdateChatRoomRequest {
resource: ChatRoom;
fieldMask: FieldMask; #2
}
The request definitions show how a string-array FieldMask travels alongside standard GET and PATCH operations without changing the resource representation. section 8.3.1
