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

application/merge-patch+json

JSON Merge Patchrequest body

application/merge-patch+json

A partial JSON document merged into the target: fields you send replace the current values, fields set to null are removed, and everything else is left alone.

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

What it looks like on the wire

PATCH /users/42 HTTP/1.1
Content-Type: application/merge-patch+json

{
  "email": "ada@example.com",
  "address": { "city": "London" },
  "nickname": null
}
Content-Type: application/merge-patch+json

Send it

fetch
await fetch("/users/42", {
  method: "PATCH",
  headers: { "Content-Type": "application/merge-patch+json" },
  body: JSON.stringify({ email: "ada@example.com", nickname: null }),
});
kubectl
kubectl patch deployment web --type merge -p '{"spec":{"replicas":3}}'

Apply it on the server

Express: parse +json bodies
app.use(express.json({ type: ["application/json", "application/*+json"] }));
JavaScript (the whole RFC 7396 algorithm)
function mergePatch(target, patch) {
  if (patch === null || typeof patch !== "object" || Array.isArray(patch)) return patch;
  const out = target && typeof target === "object" && !Array.isArray(target) ? { ...target } : {};
  for (const [key, value] of Object.entries(patch)) {
    if (value === null) delete out[key];
    else out[key] = mergePatch(out[key], value);
  }
  return out;
}

Good to know

  • Arrays are replaced whole. To add one tag you send the complete new array — or use JSON Patch.
  • Because null means "delete", a merge patch can't set a field to null. If your schema has nullable fields, use JSON Patch.
  • kubectl patch --type merge uses this format. Kubernetes' default "strategic" merge patch is its own variant that can merge lists by key.
  • Like JSON Patch, it needs express.json() configured with a type option before Express will parse it.

Frequently asked questions

Should a PATCH endpoint use merge-patch+json or plain application/json?

Many APIs accept a partial object as application/json and merge it. Declaring application/merge-patch+json makes the rules explicit — above all what null means — and lets one endpoint accept several patch formats.

How do I remove a field with JSON Merge Patch?

Set it to null in the patch. To remove a nested field, nest the null: {"address": {"line2": null}}.

Related types

Headers that go with it: Content-Type