JSON Patch is the RFC 6902 format for describing a sequence of changes to a JSON resource. A PATCH request sends operations rather than a replacement document, making targeted array updates possible. section 13.5.6
Updating an address without sending the array
For PATCH /owners/123, a JSON Patch request can use a replace operation with path /addresses/0/city and a value for the new city. The operation changes one array element without resending the entire addresses array. section 13.5.6
Choose JSON Patch deliberately rather than treating lower request volume as the only design criterion:
- Prefer JSON Merge Patch when its intuitive, widely adopted representation is sufficient for the update. section 13.5.6
- Avoid JSON Patch when documenting permitted operations with OpenAPI and JSON Schema would become complex, or when a dedicated operation better represents large-array changes. section 13.5.6
- Offer both formats through content negotiation when consumers need a choice: use application/json-patch+json for JSON Patch and merge-patch media types for JSON Merge Patch. section 13.5.6
- Do not replace JSON Merge Patch merely to work around a language’s handling of null and missing properties; native handling or JSON libraries can address that distinction. section 14.2.5
Figure 13.11 Updating the home address city with JSON Merge Patch requires sending the entire address array. With JSON Patch, we only describe the modification of the city property of the first element without needing to send the address array.
Compare the payload shapes directly: JSON Merge Patch resends the addresses array, while JSON Patch describes only the targeted city modification. section 13.5.6
