Compressed JSON Repair

Client-Side JSON Self-Repair & Healing Protocol

Overview

When an LLM generates structured JSON, minor formatting glitches frequently occur: a trailing comma before a closing bracket ([1, 2,]), single quotes ('key': 'value'), unquoted keys ({ name: "John" }), or markdown code fences enclosing the payload.

Naive agent runtimes treat a JSON.parse() exception as a fatal error and send an apologetic follow-up turn to the model ("Your JSON was invalid because of a trailing comma. Please re-generate the entire payload").

Re-prompting for trivial syntax errors burns 1,000 to 4,000 tokens and incurs 5 to 10 seconds of roundtrip latency.

The Client-Side JSON Repair Protocol intercepts malformed JSON strings and heals them locally in 1 millisecond using deterministic parser heuristics.

Re-Prompting Roundtrip vs. Client-Side Local Healing

┌─────────────────────────────────────────────────────────────┐
│                 JSON Error Recovery Flow                    │
│                                                             │
│  Re-Prompting Roundtrip (Anti-Pattern):                     │
│  • Agent Turn 1: Model outputs JSON with trailing comma     │
│  • Client: `JSON.parse()` throws SyntaxError                │
│  • Agent Turn 2: "Error: Fix JSON syntax" (Re-sends context)│
│  • Model Turn 2: Regenerates entire 800-token payload       │
│  ↳ 2 Turns, 2,400 Tokens Billed, 7.2s Latency               │
│                                                             │
│  Client-Side JSON Repair Protocol:                          │
│  • Agent Turn 1: Model outputs JSON with trailing comma     │
│  • Client: `repair_json(raw_text)` runs locally in 0.4ms    │
│  ↳ 1 Turn, 0 Wasted Tokens, 100% Immediate Execution        │
└─────────────────────────────────────────────────────────────┘

The 5 Most Common LLM JSON Glitches

Production Python JSON Repair Engine

import re
import json
from typing import Any, Dict

def repair_and_parse_json(raw_text: str) -> Dict[str, Any]:
    """Heals common LLM JSON formatting errors locally without re-prompting."""
    # 1. Strip Markdown code fences
    cleaned = re.sub(r"^```(?:json)?\s*", "", raw_text.strip(), flags=re.MULTILINE)
    cleaned = re.sub(r"\s*```$", "", cleaned, flags=re.MULTILINE).strip()
    
    # 2. Try standard parse first (Fast path)
    try:
        return json.loads(cleaned)
    except json.JSONDecodeError:
        pass

    # 3. Apply Heuristic Transformations
    # Fix trailing commas: ", ]" -> "]" and ", }" -> "}"
    cleaned = re.sub(r",\s*([\]}])", r"\1", cleaned)
    
    # Fix single quotes to double quotes
    cleaned = re.sub(r"'([^'\\]*(?:\\.[^'\\]*)*)'", r'"\1"', cleaned)
    
    # Fix unquoted keys: { key: "value" } -> { "key": "value" }
    cleaned = re.sub(r'(?<=[{,\s])([a-zA-Z0-9_]+)\s*:', r'"\1":', cleaned)
    
    # 4. Attempt second parse
    try:
        return json.loads(cleaned)
    except json.JSONDecodeError:
        # Fallback to robust external library if available (e.g. jsonrepair)
        try:
            from jsonrepair import repair_json
            return json.loads(repair_json(cleaned))
        except ImportError:
            raise ValueError(f"Fatal JSON Parse Error. Unrepairable payload: {cleaned[:100]}...")

Production TypeScript / Node.js Engine

import { jsonrepair } from "jsonrepair";

export function safeParseLLMJson<T = any>(rawText: string): T {
  // Strip code fences
  const textWithoutFences = rawText
    .replace(/^```(?:json)?/gm, "")
    .replace(/```$/gm, "")
    .trim();

  try {
    return JSON.parse(textWithoutFences);
  } catch {
    // Deterministic local healing via jsonrepair
    const healed = jsonrepair(textWithoutFences);
    return JSON.parse(healed);
  }
}

Benchmark Comparison

Evaluation across 500 synthetic malformed JSON LLM outputs:

Agent Operational Directive

MANDATORY: Agent execution runtimes must never ask an LLM to re-generate or fix a malformed JSON payload until client-side deterministic repair heuristics (jsonrepair, regex) have been attempted.