JSON diff you can apply, not just read

RFC 6902 JSON Patch is a list of instructions; RFC 7386 JSON Merge Patch is a sketch of the finished document. A JSON Patch is an array of objects — {"op":"replace","path":"/status","value":"shipped"} — that name a location with a JSON Pointer and say what to do there, so it can address a single element of an array, express a move, and be rejected cleanly if the source is not what the patch expected. A merge patch is an object shaped like the target: keys you include are set, keys you set to null are deleted, keys you leave out are untouched. Merge patch is far easier to read and to write by hand, and it pays for that by being unable to edit an array in place or to store a null.

Send it as the body of an HTTP PATCH request, or run it through a library in whatever language you use. HTTP PATCH is defined in RFC 5789 and the two formats have their own media types: application/json-patch+json and application/merge-patch+json — the download button already labels the file with the right one. Off the wire, python-jsonpatch gives you a jsonpatch command-line tool, fast-json-patch covers JavaScript, Newtonsoft.Json handles .NET and json-patch handles Go. Merge patches need no library at all in most languages, since the algorithm is a dozen lines of recursion.

Because an RFC 6902 patch is applied one operation at a time, and removing an array element renumbers everything after it. Delete index 2 and the old index 5 becomes index 4, so a patch that lists removals in ascending order deletes the wrong things from its third operation onwards — a mistake that produces a patch which applies without error and leaves a wrong document behind. Emitting removals from the highest index down means no earlier operation can shift a later one. Additions run in the opposite direction for the same reason: ascending, so that every insertion point is already correct by the time it is used.

Only when arrays are matched by identity key, because that is the only mode in which an item can be recognised in its new position. Matching by position has no way to tell a moved item from a changed one — index 0 simply holds a different value than it did — so it emits replace, add and remove and nothing else. With an identity key, the survivors are lined up in their target order with move operations, which is both shorter and truer to what happened. Copy is never emitted: it saves nothing over add when the value is already in the patch, and it makes the patch harder to read.

Because null is the syntax merge patch uses for “delete this member”, so there is nothing left to say “set this member to null” with. RFC 7386 is explicit about the trade: it chose readability over completeness, and this is the price. The same limitation applies to arrays — a merge patch cannot change one element, so any array difference at all means the whole array is resent, however long it is. This page flags both cases as they arise, path by path, so you find out here rather than after the patch has silently dropped a field in production. When either one bites, switch to RFC 6902, which can express both.

Yes — values are copied out of the source text rather than round-tripped through JavaScript numbers, so a 19-digit snowflake ID or an order number above 9,007,199,254,740,991 reaches the patch with every digit intact. This is not a detail you can take for granted: a tool built on JSON.parse and JSON.stringify turns those values into 64-bit floats first, and the patch it emits then quietly targets or writes a number that differs from yours in its last few digits.

No. Both documents are parsed, compared, patched and verified by JavaScript in this tab, so a payload full of real customer data can be turned into a patch without any of it crossing the network.