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 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:

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

Response:

{
  "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), then call execute with:

{
  "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)

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.

CLI

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/.

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: Merge base, left and right JSON arrays, returning deterministic output and explicit conflicting edit regions.
JSON keyed resolution apply: Apply explicit choices to every keyed-array merge conflict and return the fully reconstructed JSON array.
JSON array merge verify: Verify a candidate JSON array against the deterministic three-way merge result and return an exact witness.
JSON array align: Align two JSON arrays with duplicate-safe occurrence pairs and deterministic LCS tie-breaking.
JSON array anti join: Anti join two JSON arrays of objects on exact keys.