# JSON repair map offsets

`json-repair-map-offsets` · version 1.0.0 · JSON & JSONL · free, no key needed

Map code point offsets between JSON text and its lexical repair, flagging offsets that fall inside an edit.

**Use when you need to: map json parse error position back to the original text · translate offsets after repairing json · where does this repaired json position come from.**

## Decide before calling

Read the [versioned contract](/v1/tools/json-repair-map-offsets/versions/1.0.0) and the supported scope below. Reuse `json-repair-map-offsets@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-repair-map-offsets@1.0.0` for map json parse error position back to the original text. 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

- map json parse error position back to the original text
- translate offsets after repairing json
- where does this repaired json position come from
- convert positions between broken and fixed json
- source map for json repair edits
- מיפוי מיקומים בין טקסט מקורי לטקסט מתוקן

## Not supported

- map offsets for structural repairs such as closing truncated JSON
- convert between code point, UTF-16 and byte offsets
- map JSON Pointer paths to offsets

## Behavior

- Runs the json-text-repair engine on text (same six defects and refusals); unrepairable text is invalid_input with details {reason, offset}.
- Offsets are code point boundaries from 0 to the length of the source side: the original text for original_to_repaired, the repaired text for repaired_to_original. Out-of-range offsets are invalid_input.
- An offset at or before an edit start, or at or after its end, maps exactly (exact true) by the cumulative length change of the preceding edits. An offset strictly inside an edited range maps to the start of the corresponding range on the other side with exact false.
- Deletions (comments, trailing commas, byte order mark) map both their start and end to the same repaired offset; insertions of quotes around keys widen a range, so its inner repaired offsets map back inexactly.
- mappings keep the input order and duplicates. Limits: text at most 65536 UTF-8 bytes (checked first), nesting depth 64, at most 256 edits and at most 256 offsets; each overflow is limit_exceeded.

## Input

- `text` (string, required): The original JSON-like text, at most 65536 UTF-8 bytes.
- `offsets` (array of integer, required): max items 256; each min 0
- `direction` (one of "original_to_repaired", "repaired_to_original", required)

## Output

- `direction` (one of "original_to_repaired", "repaired_to_original", required)
- `original_length` (integer, required): min 0; max 131072
- `repaired_length` (integer, required): min 0; max 131072
- `edit_count` (integer, required): min 0; max 256
- `mappings` (array of object, required): max items 256

## Limits

- max text bytes: 65536
- max depth: 64
- max edits: 256
- max offsets: 256

## Example

Request input:

```json
{
  "text": "{a: 1, /*x*/ b: 2,}",
  "offsets": [
    0,
    1,
    2,
    9,
    13,
    18,
    19
  ],
  "direction": "original_to_repaired"
}
```

Response:

```json
{
  "result": {
    "direction": "original_to_repaired",
    "original_length": 19,
    "repaired_length": 17,
    "edit_count": 4,
    "mappings": [
      {
        "offset": 0,
        "mapped": 0,
        "exact": true
      },
      {
        "offset": 1,
        "mapped": 1,
        "exact": true
      },
      {
        "offset": 2,
        "mapped": 4,
        "exact": true
      },
      {
        "offset": 9,
        "mapped": 9,
        "exact": false
      },
      {
        "offset": 13,
        "mapped": 10,
        "exact": true
      },
      {
        "offset": 18,
        "mapped": 16,
        "exact": true
      },
      {
        "offset": 19,
        "mapped": 17,
        "exact": true
      }
    ]
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "json-repair-map-offsets",
  "version": "1.0.0",
  "input": {
    "text": "{a: 1, /*x*/ b: 2,}",
    "offsets": [
      0,
      1,
      2,
      9,
      13,
      18,
      19
    ],
    "direction": "original_to_repaired"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/json-repair-map-offsets/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"text":"{a: 1, /*x*/ b: 2,}","offsets":[0,1,2,9,13,18,19],"direction":"original_to_repaired"}'
```

The machine-readable contract is at [/v1/tools/json-repair-map-offsets/versions/1.0.0](/v1/tools/json-repair-map-offsets/versions/1.0.0).

### CLI

```sh
node cli.mjs run json-repair-map-offsets 1.0.0 --input input.json --base-url https://computefirst.net
```

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

## Related tools

- [JSON schema instance locate](/tools/json-schema-instance-locate): Resolve RFC 6901 instance locations (string or URI fragment) from schema errors to values, or say why they fail.
- [JSON candidate list](/tools/json-candidate-list): Find and rank JSON object/array candidates in prose and Markdown fences (quotes and lists too) with exact raw spans.
- [JSON repair diagnose](/tools/json-repair-diagnose): Classify JSON text as valid, repairable or unrepairable and locate each lexical defect and refusal by line and column.
- [JSON text repair](/tools/json-text-repair): Repair six common lexical JSON defects (comments, trailing commas, single quotes, ...) and list every edit made.
- [JSON candidate repair](/tools/json-candidate-repair): Conservatively repair a JSON candidate (comments, trailing commas, truncation), log every edit and recheck RFC 8259.
- [JSON fence extract](/tools/json-fence-extract): List Markdown fenced code blocks (CommonMark 0.31.2) with exact spans, unwrapped content and an RFC 8259 JSON check.