Json Merge Patch
A standardized way to describe a partial update to a JSON document, defined in RFC 7396 and carried as the application/merge-patch+json media type on an HTTP PATCH. The patch document mirrors the shape of the target — present members are replaced, null members are removed, and absent members are left alone — which makes it the lowest-ceremony option for partial updates when consumers should not have to send a whole resource back to change one field. Declaring merge-patch support explicitly tells consumers and agents that PATCH means RFC 7396 semantics rather than a provider-invented convention.
Also known as: Merge Patch, RFC 7396, merge-patch+json, Partial Update
Example
Standards
- IETF RFC 7396 — JSON Merge Patch
- IETF RFC 5789 — PATCH Method for HTTP
- IETF (the operation-based alternative) RFC 6902 — JavaScript Object Notation (JSON) Patch
- IETF RFC 9110 — HTTP Semantics
- IETF RFC 9457 — Problem Details for HTTP APIs
- OpenAPI Initiative OpenAPI Specification (requestBody content media types)
HTTP Headers
| Header | Direction | Spec | Description |
|---|---|---|---|
Content-Type |
request | RFC 7396 §4 | Must be application/merge-patch+json for a merge patch request body. |
Accept-Patch |
response | RFC 5789 §3.1 | Advertises which patch media types a resource accepts; the discovery hook most providers skip. |
If-Match |
request | RFC 9110 §13.1.1 | Guards against lost updates by conditioning the patch on the current ETag. |
ETag |
response | RFC 9110 §8.8.3 | Gives clients the validator to send back in If-Match on the next patch. |
Status Codes
200 OK— RFC 9110 §15.3.1 — Patch applied and the updated representation returned.204 No Content— RFC 9110 §15.3.5 — Patch applied with no representation returned.409 Conflict— RFC 9110 §15.5.10 — Patch cannot be applied against the current state of the resource.412 Precondition Failed— RFC 9110 §15.5.13 — If-Match validator no longer matches — the resource changed under the client.415 Unsupported Media Type— RFC 9110 §15.5.16 — Resource does not accept application/merge-patch+json.422 Unprocessable Content— RFC 9110 §15.5.21 — Patch is well-formed merge-patch but produces an invalid resource.
Media Types
application/merge-patch+json— RFC 7396 — The merge patch document itself.application/json-patch+json— RFC 6902 — The operation-based alternative — use when order, test, move, or array element edits matter.application/problem+json— RFC 9457 — Recommended payload for explaining a rejected patch.
OpenAPI Expression
-
paths.{path}.patch.requestBody.content(OpenAPI 3.x) — Key the request body on application/merge-patch+json and give it a schema with no required members. -
components.schemas(OpenAPI 3.x) — The patch schema is usually the resource schema with required dropped and nullable allowed, not the resource schema itself. -
responses.'415'(OpenAPI 3.x) — Document the unsupported-media-type response so clients know patch format negotiation exists.
Governance Rules
oas-operation-4xx-response(Spectral built-in) — PATCH operations should document 409, 412, and 415 alongside the success response.oas-request-body-content(Spectral (ruleset-dependent)) — Check that a PATCH request body declares an explicit patch media type rather than plain application/json.
Risk & Compliance
OWASP:
- OWASP API Security Top 10: API3:2023 Broken Object Property Level Authorization
- OWASP API Security Top 10: API6:2023 Unrestricted Access to Sensitive Business Flows
Compliance:
- SOC 2 CC8.1 — change management with traceable partial updates
- GDPR Art. 16 — right to rectification is frequently implemented as a partial update
Security: Merge patch is a mass-assignment vector by design — the patch document names the fields to change, so any writable field an attacker can guess is reachable unless the server allowlists per-property authorization. Two further traps are specific to RFC 7396: a null member means delete, so a client that serializes absent optional fields as null will silently erase data; and merge patch cannot address array elements, so array members are always replaced wholesale. Reject unknown members, authorize per property rather than per resource, and pair patches with If-Match so concurrent writers cannot clobber each other.
Tools
- JSON Merge Patch tool and API — Browser tool + hosted API for applying and generating merge patches
- json-merge-patch (npm) — JavaScript library (MIT)
- Spectral — Linter (Apache-2.0)
Suggested Metrics
patch_media_type_share— Share of PATCH operations declaring an explicit patch media type versus plain application/json.patch_415_rate— Fraction of PATCH requests rejected as unsupported media type; indicates undocumented format expectations.patch_412_rate— Fraction of PATCH requests failing a precondition; measures concurrent-write pressure.unintended_null_deletes— Count of patches whose null members removed a field the client did not intend to remove.
Example Implementations
- Kubernetes — Supports RFC 7396 merge patch alongside RFC 6902 JSON patch and its own strategic merge patch.
Related Properties
Tags
- Patch
- Partial Update
- JSON
- IETF