json_repair

json_repair is a Python library purpose-built to fix broken JSON, most commonly the kind produced by large language models that skip a closing bracket, forget to quote a key, or wrap valid JSON in explanatory prose. Instead of hand-rolling regex cleanup or wrapping every call site in try/except json.JSONDecodeError, developers drop in json_repair.loads() as a direct substitute for the standard library’s json.loads().

The library first attempts a strict json.loads() parse and only falls back to its own heuristic-driven parser when that fails, so well-formed JSON pays no performance penalty. When repair is needed, it walks the input character by character, inferring where brackets, quotes, and separators should go, recovering from truncated streaming output, Python-style tuples, and stray comments along the way.

Beyond basic repair, json_repair supports schema-guided correction: given a JSON Schema or a Pydantic v2 model, it can coerce scalar types, fill in missing required fields with safe defaults, and drop values the schema disallows — useful when the repaired JSON needs to satisfy a specific contract for storage or downstream typed processing, not just be syntactically valid. A strict mode inverts the library’s default forgiving behavior, raising ValueError on structural ambiguities instead of guessing, and a stream_stable mode keeps output stable while repairing JSON that arrives incrementally from a streaming LLM response.

The project ships both a Python API (repair_json, loads, load, from_file) and a json_repair CLI for repairing files or stdin from the command line, with pinning guidance for consumers who want the frequent minor/patch releases without breaking changes.

What You Get

• Drop-in replacements for the standard library: repair_json, loads, load, and from_file, each falling back to repair only when strict json.loads() parsing fails
• Schema-guided repair against a JSON Schema dict or a Pydantic v2 model, with a salvage mode that drops invalid array items, unwraps mis-shaped roots, and fills missing required fields from schema defaults
• A strict mode that raises ValueError on duplicate keys, missing separators, and other structural ambiguities instead of silently repairing them, for callers who want validation rather than best-effort recovery
• Stream-stable repair for partial JSON accumulated mid-stream from an LLM response, so intermediate states don’t flicker between different repaired shapes
• A json_repair command-line tool with inline-edit, custom output target, indentation, and non-ASCII handling flags for repairing files or piped stdin outside of Python code
• Full type hints (py.typed) and a public JSONReturnType type alias, checked under mypy strict mode and the ty type checker in CI

Common Use Cases

• Parsing structured output from an LLM (function-call arguments, JSON-mode completions, or prose-wrapped JSON) where the model occasionally emits a syntactically broken response
• Replacing a try: json.loads() except: cleanup_regex() pattern that has accumulated ad hoc fixes over time with a single, tested repair call
• Validating and coercing repaired JSON against a Pydantic model or JSON Schema before it’s persisted or passed to strictly-typed downstream code
• Repairing partial JSON as it streams token-by-token from a chat completion, keeping the parsed object stable between chunks
• One-off repair of malformed JSON log lines, config files, or API responses from the command line without writing a script

Under The Hood

Architecture The package splits parsing responsibility across small, single-purpose modules under src/json_repair/ — parse_object.py, parse_array.py, parse_string.py, parse_number.py, and parse_comment.py — each implementing one grammar production, composed by the central JSONParser class in json_parser.py, whose docstring notes the split was done because the parser file itself had grown to roughly 3000 lines. json_repair.py is the thin public-facing module: it tries json.loads()/json.load() first for the fast path, and only constructs a JSONParser and walks the input character-by-character when that fails, keeping well-formed JSON free of any repair overhead. Schema-guided repair is layered on top via schema_repair.py’s SchemaRepairer, which the parser consults through a TYPE_CHECKING-only import to avoid a circular dependency, and parser_schema.py/schema_repair.py together handle JSON Schema and Pydantic v2 model coercion, defaulting, and the salvage best-effort mode for structurally mismatched inputs.

Tech Stack The library targets Python 3.10+ with zero required runtime dependencies, relying entirely on the standard library (json, argparse, pathlib) for its core path; jsonschema and pydantic are pulled in only as an optional schema extra for schema-guided repair. The build uses a standard setuptools backend declared in pyproject.toml, with uv as the documented dev-environment and dependency-group manager (dev, test, typecheck, schema groups) and ruff configured with an extensive rule selection for linting and formatting. A pyproject.toml-declared console script (json_repair = "json_repair.__main__:cli") wires up the CLI entry point installed via pip or pipx.

Code Quality The test suite spans over a dozen files under tests/ covering array/object/string/number parsing, schema-guided repair, CLI behavior, strict mode, streaming stability, and type inference, and CI enforces coverage report --fail-under=100 on every pull request and push to main — a full-coverage bar rather than an aspirational one. A separate CI workflow runs mypy --strict and the ty type checker over both src/ and tests/, and a third matrix workflow runs pytest across Python 3.10 through 3.14 plus a 3.15 beta, guarding against version-specific regressions. Ruff’s linter is configured with an unusually broad rule set (bugbear, bandit, comprehensions, pylint subsets, and more) enforced via pre-commit, and the codebase is fully type-annotated with py.typed shipped for downstream type checkers.

What Makes It Unique Most JSON-repair tooling either targets a narrow class of errors or requires the caller to already know the input is broken; json_repair instead defaults to a transparent, zero-cost pass-through for valid JSON and only engages its heuristic parser on failure, so it can safely replace json.loads() everywhere rather than being reserved for known-bad inputs. Its schema-guided salvage mode goes beyond syntax repair into semantic recovery — dropping schema-invalid array items, remapping arrays to objects by property order, and inferring safe defaults for missing required fields — which is a more opinionated, LLM-output-specific feature than typical general-purpose JSON-repair libraries offer, and the stream_stable mode addresses the specific instability of repairing JSON as it arrives incrementally from a token stream.