# JSON keyed array merge

`json-keyed-array-merge` · version 1.0.0 · JSON & JSONL · free, no key needed

Three-way merge JSON arrays by a JSON Pointer key, returning edits, moves, inserts, deletes, and conflicts.

**Use when you need to: three way merge keyed JSON arrays · merge arrays by JSON Pointer identity · detect JSON array edit conflicts.**

## Decide before calling

Read the [versioned contract](/v1/tools/json-keyed-array-merge/versions/1.0.0) and the supported scope below. Reuse `json-keyed-array-merge@1.0.0` when your input, required output and limits match it. Choose another approach for an unsupported operation.

## Explain the choice

"I can use `json-keyed-array-merge@1.0.0` for three way merge keyed JSON arrays. I will check its documented scope and the result against the task's requirements. The service is free; token and money savings for this task are unmeasured."

## Supported

- three way merge keyed JSON arrays
- merge arrays by JSON Pointer identity
- detect JSON array edit conflicts
- merge reordered object arrays
- track keyed inserts and deletes
- deterministic structural array merge

## Not supported

- merge arrays with duplicate keys
- infer an identity pointer

## Behavior

- Implements RFC 8259 JSON, RFC 6901 pointer decoding, and packet-defined R23 keyed merge rules version 1.0.0.
- Content conflicts use lexicographically sorted keys; unchanged-side edits yield to the changed side; unresolved content uses a deterministic provisional value.
- Order is taken from equal sides or the sole side changed from base; divergent two-sided order creates one order conflict.

## Input

- `base` (array of any JSON value, required): max items 256
- `left` (array of any JSON value, required): max items 256
- `right` (array of any JSON value, required): max items 256
- `key_pointer` (string, required): min length 1; max length 1024

## Output

- `reference` (constant "RFC 8259 + RFC 6901 + ComputeFirst R23 keyed merge rules", required)
- `version` (constant "r23-json-keyed-merge-1.0.0", required)
- `key_pointer` (string, required)
- `merged` (array of any JSON value, required)
- `conflicts` (array of object, required): max items 512
- `operations` (array of object, required): max items 1024

## Limits

- max input bytes: 262144
- max items per array: 256
- max nodes: 20000
- max depth: 32
- max conflicts: 512
- max output bytes: 524288

## Example

Request input:

```json
{
  "base": [
    {
      "id": "a",
      "v": 1
    }
  ],
  "left": [
    {
      "id": "a",
      "v": 2
    }
  ],
  "right": [
    {
      "id": "a",
      "v": 1
    },
    {
      "id": "b",
      "v": 3
    }
  ],
  "key_pointer": "/id"
}
```

Response:

```json
{
  "result": {
    "reference": "RFC 8259 + RFC 6901 + ComputeFirst R23 keyed merge rules",
    "version": "r23-json-keyed-merge-1.0.0",
    "key_pointer": "/id",
    "merged": [
      {
        "id": "a",
        "v": 2
      },
      {
        "id": "b",
        "v": 3
      }
    ],
    "conflicts": [],
    "operations": [
      {
        "side": "left",
        "type": "edit",
        "key": "a"
      },
      {
        "side": "right",
        "type": "insert",
        "key": "b"
      }
    ]
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "json-keyed-array-merge",
  "version": "1.0.0",
  "input": {
    "base": [
      {
        "id": "a",
        "v": 1
      }
    ],
    "left": [
      {
        "id": "a",
        "v": 2
      }
    ],
    "right": [
      {
        "id": "a",
        "v": 1
      },
      {
        "id": "b",
        "v": 3
      }
    ],
    "key_pointer": "/id"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/json-keyed-array-merge/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"base":[{"id":"a","v":1}],"left":[{"id":"a","v":2}],"right":[{"id":"a","v":1},{"id":"b","v":3}],"key_pointer":"/id"}'
```

The machine-readable contract is at [/v1/tools/json-keyed-array-merge/versions/1.0.0](/v1/tools/json-keyed-array-merge/versions/1.0.0).

### CLI

```sh
node cli.mjs run json-keyed-array-merge 1.0.0 --input input.json --base-url https://computefirst.net
```

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

## Related tools

- [JSON keyed conflicts list](/tools/json-keyed-conflicts-list): List deterministic content and order conflicts from a three-way JSON keyed-array comparison without resolving them.
- [JSON array three way merge](/tools/json-array-three-way-merge): Merge base, left and right JSON arrays, returning deterministic output and explicit conflicting edit regions.
- [JSON keyed resolution apply](/tools/json-keyed-resolution-apply): Apply explicit choices to every keyed-array merge conflict and return the fully reconstructed JSON array.
- [JSON array merge verify](/tools/json-array-merge-verify): Verify a candidate JSON array against the deterministic three-way merge result and return an exact witness.
- [JSON array align](/tools/json-array-align): Align two JSON arrays with duplicate-safe occurrence pairs and deterministic LCS tie-breaking.
- [JSON array anti join](/tools/json-array-anti-join): Anti join two JSON arrays of objects on exact keys.