# JSON deep diff

`json-deep-diff` · version 1.0.0 · JSON & JSONL · free, no key needed

Bounded deterministic JSON difference records. Not a JSON Patch implementation.

**Use when you need to: json deep diff · diff json values · json structural diff.**

## Supported

- json deep diff
- diff json values
- json structural diff

## Not supported

- json patch apply
- json merge patch
- text diff

## Behavior

- Accept only JSON values: null, boolean, finite number, string, array, and plain objects.
- Reject NaN, Infinity, -Infinity, undefined, BigInt, functions, symbols, Date, Map, Set, RegExp, boxed primitives, Buffer, and sparse holes.
- Canonicalize -0 to 0.
- Objects may have null or Object.prototype; comparison uses own enumerable string keys only.
- Treat __proto__, constructor, and toString as ordinary own keys. Never mutate Object.prototype.
- Output objects are Object.create(null). Returned JSON values are deep-cloned.
- Bound walk: max depth 32, max nodes 10000 per value.
- Object keys are compared using the sorted union of own keys (UTF-16 lexicographic). Arrays are index-aligned; extra tail elements are add/remove.
- Each change is { pointer, op, left?, right? } where op is replace | add | remove. This is not RFC 6902 JSON Patch.
- replace: both present and not equal (left from a, right from b). add: only in b. remove: only in a.
- Do not recurse into a subtree after emitting replace/add/remove for that node.
- More than 1000 changes is rejected.

## Input

- `a` (any JSON value, required)
- `b` (any JSON value, required)

## Output

- `changes` (array of object, required): max items 1000

## Limits

- max json depth: 32
- max json nodes: 10000
- max changes: 1000

## Example

Request input:

```json
{
  "a": {
    "x": 1,
    "y": 2
  },
  "b": {
    "x": 1,
    "y": 3,
    "z": 4
  }
}
```

Response:

```json
{
  "result": {
    "changes": [
      {
        "pointer": "/y",
        "op": "replace",
        "left": 2,
        "right": 3
      },
      {
        "pointer": "/z",
        "op": "add",
        "right": 4
      }
    ]
  }
}
```

## How to call it

### MCP

Connect `https://computefirst.net/mcp` ([setup](/docs#connect)), then call `execute` with:

```json
{
  "id": "json-deep-diff",
  "version": "1.0.0",
  "input": {
    "a": {
      "x": 1,
      "y": 2
    },
    "b": {
      "x": 1,
      "y": 3,
      "z": 4
    }
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/json-deep-diff/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"a":{"x":1,"y":2},"b":{"x":1,"y":3,"z":4}}'
```

The machine-readable contract is at [/v1/tools/json-deep-diff/versions/1.0.0](/v1/tools/json-deep-diff/versions/1.0.0).

### CLI

```sh
node cli.mjs run json-deep-diff 1.0.0 --input input.json --base-url https://computefirst.net
```

Get the client at [/clients/cli/](/clients/cli/).

## Related tools

- [JSON deep equal](/tools/json-deep-equal): JSON-only structural equality. Object key order does not matter; array order does.
- [JSON array count](/tools/json-array-count): Count structural occurrences in a JSON array in first-seen order.
- [JSON array unique](/tools/json-array-unique): Deduplicate a JSON array by structural equality, keeping first-seen order.
- [Array to JSONL](/tools/array-to-jsonl): Serialize an array of JSON-safe values as JSON Lines text.
- [JSON array anti join](/tools/json-array-anti-join): Anti join two JSON arrays of objects on exact keys.
- [JSON array concat](/tools/json-array-concat): Concatenate multiple JSON arrays of objects into one.