To clear a field in a PATCH request, follow the target API’s documented contract: some APIs require the field in an update mask while omitting its value from the resource body; others require the property in the JSON body with a value of null. These payloads are not interchangeable. Google’s Docs, BigQuery, and Wallet documentation illustrate both approaches.
Why PATCH does not tell you how to clear a field
PATCH indicates a partial update, but it does not by itself specify what omission or null means for a particular field. The endpoint’s update semantics determine whether either form clears the value—or whether it has some other effect.
Google’s AIP-134 update guidance generally uses PATCH for resource updates. It describes an update_mask that identifies which fields the request changes. If the mask is omitted, the guidance treats it as an implied mask covering the fields populated in the request. For a specific API, check its method documentation for the accepted mask name, field paths, and clearing behavior.
Pattern 1: select the field in an update mask and omit its value
In the Google Docs API’s documented field-mask behavior, a field is unset by naming it in the mask but leaving it out of the updated message. The mask selects the field to change; the absent value signals that it should be cleared.
#1 Best Overall
{
"book": { "name": "publishers/123/books/456" },
"updateMask": "description"
}This is an illustrative shape, not a complete request. Its meaning depends on the target method supporting this update-mask behavior. The Google Docs field-mask guidance states that a field can be unset by leaving it out of the updated message and adding it to the mask. For nested fields, field masks use field-path syntax; consult the API’s documentation for the exact path and request format. AIP-161 describes Google’s field-mask conventions.
Pattern 2: include the property and set it to JSON null
BigQuery and Google Wallet document a different deletion form: include the property in the PATCH body and assign it JSON null.
Rank #2
{
"comment": null
}The BigQuery API performance guide gives this as the way to delete a field. Google Wallet’s performance guidance describes the same null-deletion rule. This is JSON null—not the string "null".
How the two documented patterns compare
| Decision | Field-mask omission | Explicit-null property |
|---|---|---|
| How the field is selected | Name it in update_mask; nested fields use field-path syntax. See AIP-134 and AIP-161. |
Include the property in the JSON request body. See the BigQuery guidance. |
| What goes in the body | Leave the selected field’s value out of the updated resource; Google Docs documents this as unsetting it. See Google Docs field masks. | Set the property’s value to JSON null; BigQuery and Wallet document this as deleting it. See BigQuery and Wallet. |
| Safe choice | Use only when the target method specifies the relevant update-mask semantics. | Use only when the target endpoint specifies null as the deletion form. |
Why Google APIs use PATCH for updates
AIP-134 explains a compatibility reason for preferring PATCH over full-resource PUT replacement. An older client may not know about a field added to a resource later. If it sends a full PUT body without that field, replacement can erase the newer value. PATCH lets a client update selected data without replacing fields it does not know about.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Arrays may be replaced rather than edited item by item
In the PATCH behavior described by BigQuery and Google Wallet, an array is replaced by the supplied array. Those guides do not describe piecemeal additions, removals, or edits of individual array elements through that behavior. Check the specific endpoint before assuming the same rule applies elsewhere.
Quick Recap
Choose the payload from the endpoint documentation
- Identify the exact API method and resource field you intend to clear.
- Check whether the method uses an update mask, explicit JSON null, or another documented rule for clearing that field.
- Build the body to match that rule: omit the value while retaining the field in the mask, or include the property with a
nullvalue, as specified. - Check any documented array behavior separately if the field is an array.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
