JSON Diff and Patch Workflow: Track Changes Like a Pro

JSON diffing and patching are essential for tracking changes, reviewing modifications, and applying updates to JSON documents. Whether you are comparing API responses, reviewing configuration changes, or implementing collaborative editing, understanding JSON diff/patch workflows saves time and prevents errors. This guide covers the JSON Patch format (RFC 6902), JSON Merge Patch (RFC 7396), diff algorithms, and practical workflows. Use our JSON Diff Checker and JSON Patch Generator to apply these concepts instantly.

What is JSON Diff?

A JSON diff identifies the differences between two JSON documents. At a minimum, it reports which fields were added, removed, or changed. Advanced diffs show the exact path to each change, the old and new values, and can generate machine-readable patch documents.

What is JSON Patch (RFC 6902)?

JSON Patch is a format (RFC 6902) for describing changes to a JSON document as a sequence of operations. Each operation has an op (add, remove, replace, move, copy, test) and a path (JSON Pointer).

// Original document
{
  "name": "Alice",
  "age": 30,
  "email": "alice@old.com"
}

// Patch operations
[
  { "op": "replace", "path": "/age", "value": 31 },
  { "op": "replace", "path": "/email", "value": "alice@new.com" },
  { "op": "add", "path": "/phone", "value": "555-0100" }
]

// Result
{
  "name": "Alice",
  "age": 31,
  "email": "alice@new.com",
  "phone": "555-0100"
}

JSON Patch Operations Reference

Operation	Description	Example
add	Add a value at the specified path	{"op":"add","path":"/items/-","value":"new"}
remove	Remove the value at the specified path	{"op":"remove","path":"/obsolete"}
replace	Replace the value at path with a new one	{"op":"replace","path":"/name","value":"Bob"}
move	Move a value from one path to another	{"op":"move","from":"/old","path":"/new"}
copy	Copy a value from one path to another	{"op":"copy","from":"/template","path":"/target"}
test	Test that a value matches (for conditional patching)	{"op":"test","path":"/version","value":2}

JSON Merge Patch (RFC 7396)

JSON Merge Patch is a simpler alternative. Instead of an array of operations, you send a partial document:

// Original
{ "a": "x", "b": "y", "c": { "d": "z" } }

// Merge patch
{ "a": "updated", "c": null }

// Result
{ "a": "updated", "b": "y" }  // c removed, a updated, b unchanged

Use Merge Patch for simple updates and JSON Patch for complex transformations. Our JSON Patch Generator supports both formats.

Diff Algorithms: Deep vs Shallow

Algorithm	Speed	Accuracy	Use Case
Shallow (top-level keys only)	Very fast	Low — misses nested changes	Quick config checks
Recursive (deep comparison)	Fast	High — compares all nested values	Most use cases
Array-aware (value-based)	Moderate	High — detects insertions and deletions	Ordered lists
LCS-based (Longest Common Subsequence)	Slow on large arrays	Highest — finds optimal edit sequence	Version control diffs

JavaScript Diff Implementation

function deepDiff(obj1, obj2, path = '') {
  const diffs = [];

  // Check for added/removed keys
  const allKeys = new Set([
    ...Object.keys(obj1 || {}),
    ...Object.keys(obj2 || {})
  ]);

  for (const key of allKeys) {
    const currentPath = path ? path + '.' + key : key;
    const val1 = obj1?.[key];
    const val2 = obj2?.[key];

    if (!(key in obj1)) {
      diffs.push({ op: 'add', path: '/' + currentPath, value: val2 });
    } else if (!(key in obj2)) {
      diffs.push({ op: 'remove', path: '/' + currentPath });
    } else if (typeof val1 === 'object' && typeof val2 === 'object'
        && val1 !== null && val2 !== null) {
      diffs.push(...deepDiff(val1, val2, currentPath));
    } else if (val1 !== val2) {
      diffs.push({ op: 'replace', path: '/' + currentPath, value: val2 });
    }
  }
  return diffs;
}

Applying Patches

import { applyPatch } from 'json-patch';

const doc = { name: "Alice", age: 30 };
const patch = [
  { op: "replace", path: "/age", value: 31 },
  { op: "add", path: "/phone", value: "555-0100" }
];

const result = applyPatch(doc, patch);
// { name: "Alice", age: 31, phone: "555-0100" }

Workflow for API Testing

1. Capture the baseline API response (use JSON Formatter)
2. Make changes to your application
3. Capture the new response
4. Diff the two responses with JSON Diff Checker
5. If the diff is expected, generate a patch with JSON Patch Generator
6. Apply the patch in your deployment pipeline

Next Steps

Diff your JSON documents with JSON Diff Checker. Generate patches with JSON Patch Generator. Compare side-by-side with JSON Compare. For schema-level diffs, use JSON Schema Diff.