JSON Patch Generator

When an API lets clients update part of a resource, the request has to describe what changed. Two IETF standards do that for JSON: JSON Patch, a list of operations, and JSON Merge Patch, a partial document. This tool compares two versions of a document and produces either format, and it can apply a patch to see exactly what it does.

JSON Patch in brief

A JSON Patch (RFC 6902) is an array of operation objects. Each has an op, a path and, depending on the operation, a value or a from. add inserts a value, remove deletes one, replace changes one, move and copy take a value from one path to another, and test checks that a value is what you expect. Operations run in order, so later ones see the effect of earlier ones. Requests carrying a patch use the media type application/json-patch+json.

JSON Pointer paths

Paths use JSON Pointer (RFC 6901): a slash-separated list of keys and array indexes from the root, such as /address/postcode or /roles/1. The special index - means “after the last element” and is used to append. Because keys may contain slashes and tildes, those characters are escaped: ~1 stands for / and ~0 for ~, so a key named a/b is addressed as /a~1b.

How the diff is computed

The generator walks both documents together. For objects it compares key by key: keys missing from the new version become remove, new keys become add, and changed values are compared recursively until they differ, which becomes a replace at the deepest changed path. Arrays are compared position by position. Extra elements are removed from the end first, so the indexes of earlier removals stay valid, and new elements are appended with /-. Finally, the patch is applied to the original and compared with the target, and the round-trip check reports whether they match.

Merge Patch

A Merge Patch (RFC 7396) is simpler: a JSON object containing only the fields that change, with nested objects merged recursively and null meaning “delete this key”. It is easy to read and easy to write by hand, which is why many APIs accept it with the media type application/merge-patch+json. Its limits follow from that design: it cannot set a value to null, and an array is always replaced as a whole.

A worked example

The Sample changes a user record. The JSON Patch has seven operations: remove /newsletter, replace /name with “Ada King”, replace /roles/1 with “admin”, add “owner” at /roles/-, replace /address/postcode with “W1A 1AA”, add /address/country as “GB” and add /phone. The round-trip check passes. The merge patch for the same change is { "newsletter": null, "name": "Ada King", "roles": ["editor", "admin", "owner"], "address": { "postcode": "W1A 1AA", "country": "GB" }, "phone": "+44 20 7946 0000" }, which repeats the whole roles array.

Applying patches

In apply mode, paste a document and a patch to see the result. replace changes a value in place, so object keys keep their position. move and copy need a from path, and test fails the whole patch when a value differs. If an operation fails, for example because a path does not exist, the error names the operation by number and explains why.

Choosing a format

Use Merge Patch for simple field updates from forms and settings screens. Use JSON Patch when you need to change single array elements, express moves, set values to null or add a test guard against concurrent edits. The diff does not detect elements moved within an array; a reordered list becomes several replace operations, which is correct but not minimal.

Related tools

• Diff Checker compares two texts line by line.
• JSON Formatter validates and tidies the documents first.
• JSONPath Tester finds values inside large documents.
• YAML to JSON converts YAML configuration before diffing it.