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

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

Response:

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

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

HTTP (no key)

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.

CLI

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

Get the client at /clients/cli/.

Related 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: List Markdown fenced code blocks (CommonMark 0.31.2) with exact spans, unwrapped content and an RFC 8259 JSON check.
• JSON text repair: Repair six common lexical JSON defects (comments, trailing commas, single quotes, ...) and list every edit made.
• JSON candidate repair: Conservatively repair a JSON candidate (comments, trailing commas, truncation), log every edit and recheck RFC 8259.
• 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: List every property a JSON Schema 2020-12 "required" keyword demands but the instance lacks, with JSON Pointers.