# JSON array align

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

Align two JSON arrays with duplicate-safe occurrence pairs and deterministic LCS tie-breaking.

**Use when you need to: align two JSON arrays · find common JSON array sequence · match duplicate array occurrences.**

## Decide before calling

Read the [versioned contract](/v1/tools/json-array-align/versions/1.0.0) and the supported scope below. Reuse `json-array-align@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-array-align@1.0.0` for align two 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

- align two JSON arrays
- find common JSON array sequence
- match duplicate array occurrences
- compute deterministic array LCS
- map array indexes by value
- compare ordered JSON values

## Not supported

- merging JSON objects by key
- reading JSON text or files

## Behavior

- Values are compared by RFC 8259 JSON structure with object member names sorted; array order and number spelling after parsing follow JavaScript JSON values.
- Alignment uses longest common subsequence; on equal alternatives it advances the first input, a deterministic deletion-before-insertion tie rule. Duplicate values are identified by matched occurrence, never by value alone.
- The implementation is synchronous, offline and deterministic and reports RFC 8259 + Myers 1986 and version 1.0.0.

## Input

- `left` (array of any JSON value, required): max items 128
- `right` (array of any JSON value, required): max items 128

## Output

- `reference` (constant "RFC 8259 + Myers 1986", required)
- `version` (constant "1.0.0", required)
- `pairs` (array of object, required): max items 128
- `left_only` (array of integer, required): max items 128; each min 0; each max 127
- `right_only` (array of integer, required): max items 128; each min 0; each max 127

## Limits

- max input bytes: 65536
- max items: 128
- max iterations: 49152
- max output bytes: 131072

## Example

Request input:

```json
{
  "left": [
    "a",
    "b"
  ],
  "right": [
    "a",
    "c",
    "b"
  ]
}
```

Response:

```json
{
  "result": {
    "reference": "RFC 8259 + Myers 1986",
    "version": "1.0.0",
    "pairs": [
      {
        "left_index": 0,
        "right_index": 0,
        "occurrence": 1
      },
      {
        "left_index": 1,
        "right_index": 2,
        "occurrence": 1
      }
    ],
    "left_only": [],
    "right_only": [
      1
    ]
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "json-array-align",
  "version": "1.0.0",
  "input": {
    "left": [
      "a",
      "b"
    ],
    "right": [
      "a",
      "c",
      "b"
    ]
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/json-array-align/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"left":["a","b"],"right":["a","c","b"]}'
```

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

### CLI

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

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

## Related tools

- [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 array merge](/tools/json-keyed-array-merge): Three-way merge JSON arrays by a JSON Pointer key, returning edits, moves, inserts, deletes, and conflicts.
- [JSON schema valid items filter](/tools/json-schema-valid-items-filter): Keep only the JSON records that pass (or fail) one Draft 2020-12 subset schema; returns kept records and index lists.
- [JSON array anti join](/tools/json-array-anti-join): Anti join two JSON arrays of objects on exact keys.
- [JSON array count](/tools/json-array-count): Count structural occurrences in a JSON array in first-seen order.
- [JSON array filter equals](/tools/json-array-filter-equals): Filter JSON array objects where a key equals a specific value.