# JSON repair diagnose

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

Classify JSON text as valid, repairable or unrepairable and locate each lexical defect and refusal by line and column.

**Use when you need to: why is this json invalid · find lexical errors in json text · can this broken json be repaired safely.**

## Decide before calling

Read the [versioned contract](/v1/tools/json-repair-diagnose/versions/1.0.0) and the supported scope below. Reuse `json-repair-diagnose@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-diagnose@1.0.0` for why is this json invalid. 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

- why is this json invalid
- find lexical errors in json text
- can this broken json be repaired safely
- line and column of json syntax problems
- count trailing commas and comments in json
- check llm json output before parsing
- אבחון שגיאות תחביר בפלט נתונים

## Not supported

- return the repaired text (use json-text-repair)
- validate JSON against a schema
- report every error after the first unrepairable one

## Behavior

- Uses exactly the json-text-repair engine (ECMA-404 / RFC 8259 grammar plus six repairable defects: byte_order_mark, comment, trailing_comma, single_quoted_string, unquoted_key, python_literal). It never throws for unrepairable text; it reports it.
- status is "valid" (strict JSON, no defects), "repairable" (json-text-repair would succeed with defect_count edits) or "unrepairable" (refusal is set to the first refusal reason and its position).
- defects lists every defect in text order when repairable; when unrepairable it lists only the defects found before the refusal point. counts always has all six kinds.
- Offsets are code point indices; line and column are 1-based, columns count code points, and LF, CR and CRLF each end one line (RFC 8259 whitespace).
- Refusal reasons: empty_text, unexpected_character, unexpected_token, unexpected_end, trailing_content, unterminated_string, invalid_escape, control_character_in_string, invalid_number, unknown_identifier, ambiguous_key, unterminated_comment, duplicate_key (names compared after decoding, at every nesting level).
- Limits: text at most 65536 UTF-8 bytes (checked first), nesting depth at most 64, at most 256 defects; each overflow is limit_exceeded rather than a partial report.

## Input

- `text` (string, required): JSON-like text, at most 65536 UTF-8 bytes.

## Output

- `status` (one of "valid", "repairable", "unrepairable", required)
- `defect_count` (integer, required): min 0; max 256
- `counts` (object, required)
- `defects` (array of object, required): max items 256
- `refusal` (null or object, required)

## Limits

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

## Example

Request input:

```json
{
  "text": "{'a': 1,\n 'b': None}"
}
```

Response:

```json
{
  "result": {
    "status": "repairable",
    "defect_count": 3,
    "counts": {
      "byte_order_mark": 0,
      "comment": 0,
      "trailing_comma": 0,
      "single_quoted_string": 2,
      "unquoted_key": 0,
      "python_literal": 1
    },
    "defects": [
      {
        "kind": "single_quoted_string",
        "start": 1,
        "end": 4,
        "line": 1,
        "column": 2
      },
      {
        "kind": "single_quoted_string",
        "start": 10,
        "end": 13,
        "line": 2,
        "column": 2
      },
      {
        "kind": "python_literal",
        "start": 15,
        "end": 19,
        "line": 2,
        "column": 7
      }
    ],
    "refusal": null
  }
}
```

## How to call it

### MCP

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

```json
{
  "id": "json-repair-diagnose",
  "version": "1.0.0",
  "input": {
    "text": "{'a': 1,\n 'b': None}"
  }
}
```

### HTTP (no key)

```sh
curl -X POST https://computefirst.net/v1/tools/json-repair-diagnose/versions/1.0.0/execute \
  -H "Content-Type: application/json" \
  -d '{"text":"{'\''a'\'': 1,\n '\''b'\'': None}"}'
```

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

### CLI

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

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

## Related tools

- [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 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.
- [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 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 schema required missing](/tools/json-schema-required-missing): List every property a JSON Schema 2020-12 "required" keyword demands but the instance lacks, with JSON Pointers.