Documentation

JSON Patch vs JSON Diff

The two most confused terms in the JSON world. A diff answers "what changed between these two documents?" A patch answers "what operations turn this document into that one?" - in a form a machine can apply.

What a JSON diff is

A diff is the output of comparing two documents. There is no single standard for it: git-style unified diffs show changed lines, tree diffs show changed paths, and every online "compare JSON" tool has its own visual convention. What they share is the audience: diffs are made for people. You read one to review a config change, debug an API response, or audit what a deploy touched.

The JSON Diff tool on this site highlights every added, removed and edited value with its exact path - and because this is a JSON Patch site, it also shows the same change expressed as RFC 6902 operations.

What a JSON Patch is

JSON Patch is an IETF standard (RFC 6902): a JSON array of operations, each naming an op, a path, and usually a value. Unlike a diff, a patch is executable: any conforming library in any language can apply it, operations run in order, and evaluation stops when an operation fails. RFC 6902 does not require rollback of earlier operations.

[
  { "op": "replace", "path": "/version", "value": 2 },
  { "op": "add", "path": "/tags", "value": ["a"] }
]

{ "name": "demo", "version": 1 }

{ "name": "demo", "version": 2, "tags": ["a"] }

How the two relate

Generating a patch is diffing: the generator compares the two documents and emits the operations that describe the differences. Applying a patch is the reverse trip: it reproduces the second document from the first without ever seeing it. That is why the same tool on this site does both - the visual diff is the human view of the change, the patch is the machine view.

• Reading a change - you want a diff: review, debug, audit.
• Replaying a change - you want a patch: API updates, config rollouts, syncing state.
• Guarding a change - only a patch can do it: the test operation stops evaluation if the document is not in the expected state.

When to use which

Use a diff when the output is for a person: code review, "what did this deploy change", comparing two API responses. Use a patch when the output is for a program: HTTP PATCH endpoints that accept application/json-patch+json, database updates that should only touch modified fields, or any flow where the change must be replayed exactly and as an ordered sequence. If you need both - review first, apply later - generate the patch and read the visual diff of the same change.

Common mistakes