liveBook · Manning

JSON Merge Patch

As explained in The Design of Web APIs, Second Edition

JSON Merge Patch is a standardized JSON-based format for describing modifications to a target JSON document through a partial replacement structure.

JSON Merge Patch (RFC 7396) lets a consumer send the data to modify in a PATCH request rather than send a complete resource as with PUT. A modification model can make its properties optional and omit fields that cannot be changed after creation. section 5.3.4 section 13.5.6

Changing an account owner's home city

With PATCH /owners/123, a merge patch changing the home address city must include the entire addresses array, with the other address and unchanged data retained. JSON Patch can instead identify the city by a JSON pointer and replace just that value. Its smaller request comes with a more complex format. section 13.5.6

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.
figure

Compare the data each format sends to change one city within an address array. section 13.5.6

Prefer the simpler, widely adopted merge patch for ordinary partial updates. If large arrays make replacement costly, consider dedicated operations; content negotiation can also support JSON Patch alongside merge patch. An implementation must distinguish a JSON key whose value is null from a missing key rather than treating that distinction as a reason to reject merge patch. section 13.5.6 section 14.2.5

How The Design of Web APIs, Second Edition covers it

How deep it goes
Explains optional-field models, array-update trade-offs, media types and a null-versus-missing implementation concern without detailing a patch algorithm.
Examples
Contrasts PATCH requests that change an account owner's home city using a full address array or a JSON Patch operation.
What it assumes
Assumes familiarity with JSON resources and HTTP update methods while introducing their use for partial updates.
What you can do after
Practice/perform partial updates with HTTP PATCH, accounting for restricted fields and the cost of changing arrays.
How it connects
Connects HTTP PATCH and PUT with JSON Patch, content negotiation, OpenAPI and JSON Schema.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.