# application/merge-patch+json: JSON Merge Patch (RFC 7396)

> 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 type: `application/merge-patch+json`
- Used for: Request body
- Parameters: None
- Specification: [RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)

## Example

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

{
  "email": "ada@example.com",
  "address": { "city": "London" },
  "nickname": null
}
```

## 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](https://www.devkult.com/mime/json-patch.md).
- 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.

## FAQ

### 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

- [application/json-patch+json](https://www.devkult.com/mime/json-patch.md)
- [application/problem+json](https://www.devkult.com/mime/problem-json.md)

Open the interactive page: https://www.devkult.com/mime/merge-patch