A Google Docs API field mask limits which properties an update changes. Use explicit property names so a formatting operation preserves unrelated values and does not become broader when the API adds fields later.
Choose an update mask deliberately
For a text-style update that should only change bold, set the intended textStyle value and use fields: "bold". For several justified properties, list only those supported fields.
Google warns against wildcard masks in production. A wildcard means every field in the message and can create unwanted behavior as the interface evolves.
Understand clearing behavior
- Identify the exact property to change.
- Provide its intended value when setting it.
- Include it in the update mask.
- Inspect omitted values carefully before sending.
A property included in the mask but omitted from the updated message can be cleared. Do not construct a broad mask automatically from a generic object whose missing values were never reviewed.
Keep read masks separate
The fields URL parameter on a read controls the returned representation. It does not grant access, prove omitted content does not exist, or establish the scope of a later update.
When reading a tabbed document, request the tab content and structural information needed for the task. After a narrow update, verify both the changed property and representative unrelated properties. Test the exact request shape against controlled content and retain appropriate revision protection. A minimal response can improve efficiency, but it should not conceal that the application lacks enough information to target or verify its edits safely.
References
- Use field masks | Google Docs | Google for Developers
- Format Text | Google Docs | Google for Developers
Reviewed against the linked official product guidance on November 3, 2026. Features, limits, screen labels, and access can vary by account, platform, region, and organization policy.