devkult_
tools30converters34
home/mime/application/json-patch+json

application/json-patch+json

JSON Patchrequest body

application/json-patch+json

A list of operations — add, remove, replace, move, copy and test — that a PATCH request applies to a JSON document.

MIME typeapplication/json-patch+json
Used forRequest body
ParametersNone
SpecificationRFC 6902

What it looks like on the wire

PATCH /users/42 HTTP/1.1
Content-Type: application/json-patch+json
If-Match: "v7"

[
  { "op": "test", "path": "/version", "value": 7 },
  { "op": "replace", "path": "/email", "value": "ada@example.com" },
  { "op": "add", "path": "/tags/-", "value": "admin" },
  { "op": "remove", "path": "/nickname" }
]
Content-Type: application/json-patch+json

Send it

fetch
await fetch("/users/42", {
  method: "PATCH",
  headers: { "Content-Type": "application/json-patch+json" },
  body: JSON.stringify([{ op: "replace", path: "/email", value: "ada@example.com" }]),
});
curl
curl -X PATCH -H 'Content-Type: application/json-patch+json' \
  -d '[{"op":"remove","path":"/nickname"}]' https://api.example.com/users/42

Apply it on the server

Express: parse +json bodies
app.use(express.json({ type: ["application/json", "application/*+json"] }));
JavaScript (fast-json-patch)
import { applyPatch } from "fast-json-patch";

const updated = applyPatch(doc, patch, true).newDocument; // true = validate operations
Python (jsonpatch)
import jsonpatch

updated = jsonpatch.apply_patch(doc, patch)

Good to know

  • Paths are JSON Pointers (RFC 6901): /tags/0 is the first array item, /tags/- appends to the array, and ~1 and ~0 escape / and ~ inside keys.
  • A patch is atomic: if any operation fails, none are applied. Put a test operation first to make the whole patch conditional on the current value.
  • express.json() only parses application/json by default, so a patch body arrives as an empty object until you pass the type option shown above.
  • Servers can advertise the patch formats they accept with the Accept-Patch response header (RFC 5789).

Useful here: JSON diff

Frequently asked questions

What is the difference between JSON Patch and JSON Merge Patch?

JSON Patch is a list of explicit operations and can express anything, including edits to single array elements. JSON Merge Patch is a partial document merged into the target — simpler to write, but it can't set a value to null or change part of an array.

Which status code should a failed JSON Patch return?

RFC 5789 suggests 400 for a malformed patch, 415 for a patch format the server doesn't support, 422 when the patch is valid but can't be applied (for example a failed test), and 409 when the resource is in a conflicting state.

Related types

Headers that go with it: Content-Type · If-Match