JSON Diff API: The Complete Guide to JSON Comparison

Need to compare JSON objects and find what changed? This guide covers everything you need to know about JSON diffing via API, including different output formats and implementation examples in multiple languages.

What is JSON Diff?

JSON diff is the process of comparing two JSON objects to identify differences between them. The result shows what was added, removed, or modified, similar to how Git shows file changes.

For example, comparing {"name": "John"} with {"name": "Jane"} shows that the "name" field changed from "John" to "Jane".

Diff Output Formats

Different formats serve different purposes:

RFC 6902 JSON Patch

Standard format describing operations (add, remove, replace, move, copy). Can be applied to recreate the target from source.

Simple Diff

Human-readable list of changes showing path, old value, and new value. Easier to understand at a glance.

Semantic Diff

Groups related changes and handles array reordering intelligently. Better for complex objects.

Using the JSON Diff API

TinyFn provides a simple endpoint to compare JSON objects:

POST https://api.tinyfn.io/v1/json/diff
Headers: X-API-Key: your-api-key
Content-Type: application/json

{
  "source": {"name": "John", "age": 30, "city": "NYC"},
  "target": {"name": "Jane", "age": 30, "country": "USA"}
}

{
  "changes": [
    {"op": "replace", "path": "/name", "value": "Jane", "oldValue": "John"},
    {"op": "remove", "path": "/city", "oldValue": "NYC"},
    {"op": "add", "path": "/country", "value": "USA"}
  ],
  "patch": [
    {"op": "replace", "path": "/name", "value": "Jane"},
    {"op": "remove", "path": "/city"},
    {"op": "add", "path": "/country", "value": "USA"}
  ],
  "identical": false,
  "changeCount": 3
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/json/diff',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      source: { name: 'John', age: 30, city: 'NYC' },
      target: { name: 'Jane', age: 30, country: 'USA' }
    })
  }
);
const { changes, identical, changeCount } = await response.json();
console.log(`Found ${changeCount} changes:`);
changes.forEach(c => {
  console.log(`${c.op}: ${c.path} = ${c.value || c.oldValue}`);
});
// Found 3 changes:
// replace: /name = Jane
// remove: /city = NYC
// add: /country = USA

Python

import requests

response = requests.post(
    'https://api.tinyfn.io/v1/json/diff',
    json={
        'source': {'name': 'John', 'age': 30, 'city': 'NYC'},
        'target': {'name': 'Jane', 'age': 30, 'country': 'USA'}
    },
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(f"Found {data['changeCount']} changes:")
for change in data['changes']:
    print(f"{change['op']}: {change['path']}")
# Found 3 changes:
# replace: /name
# remove: /city
# add: /country

cURL

curl -X POST "https://api.tinyfn.io/v1/json/diff" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {"name": "John", "age": 30, "city": "NYC"},
    "target": {"name": "Jane", "age": 30, "country": "USA"}
  }'

Common Use Cases

• Configuration Auditing: Track changes to app configurations
• API Response Comparison: Compare responses between environments
• Data Synchronization: Identify changes needed to sync databases
• Version Control: Show document changes in collaborative editing
• Testing: Compare expected vs actual JSON in tests

Best Practices

1. Normalize before comparing: Sort keys and format consistently
2. Handle arrays carefully: Decide between order-sensitive and set comparison
3. Limit depth: Very deep objects may have performance implications
4. Use JSON Patch for automation: Apply patches programmatically

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-json": {
      "url": "https://api.tinyfn.io/mcp/json/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all json tools available via MCP in our JSON MCP Tools for AI Agents guide.