json-repair

Repairs syntactically broken JSON by using ANTLR parser to identify structural errors (missing braces, brackets, parentheses) and applies configurable repair strategies (SimpleRepairStrategy, CorrectRepairStrategy) to fix them. The JSONRepair orchestrator class manages the repair pipeline, attempting fixes iteratively up to a configurable limit, with error context tracking via the Expecting class to understand what tokens are missing at failure points.

Extracts valid JSON objects or arrays from larger text blocks (e.g., LLM responses with explanatory text before/after JSON) using SimpleExtractStrategy, which scans for JSON delimiters and isolates contiguous JSON content. Extracted JSON is then passed through the repair pipeline if it contains anomalies, enabling end-to-end recovery of structured data from unstructured LLM outputs.

Includes comprehensive integration tests (IntegrationTests class) covering a wide range of JSON anomalies produced by LLMs: missing braces/brackets, unquoted keys/values, trailing commas, missing outer delimiters, and nested structure errors. Tests are organized by anomaly type and include both positive cases (repair succeeds) and negative cases (repair fails gracefully), providing confidence in repair behavior across different LLM output patterns.

Implements a configurable repair pipeline via JSONRepairConfig that allows developers to set maximum repair attempt counts and extraction modes. The JSONRepair orchestrator applies repair strategies iteratively, re-parsing after each fix attempt until either the JSON is valid or the attempt limit is reached. This prevents infinite loops while allowing heuristic-based repairs to converge on valid output through multiple passes.

Tracks parse error context through the Expecting class, which records what tokens the parser expected at the point of failure (e.g., 'expected }' or 'expected ]'). This error context is used by repair strategies to make targeted fixes rather than blind string manipulation. When ANTLR parsing fails, the Expecting object captures the expected token type and position, enabling the repair strategy to insert the correct missing delimiter at the right location.

Repairs JSON where keys or values lack quotation marks (e.g., {f:v} instead of {"f":"v"}) by detecting unquoted identifiers and automatically inserting quotes around them. This is handled as part of the SimpleRepairStrategy, which identifies tokens that should be strings but lack delimiters and wraps them in quotes during the repair pass.

Removes redundant or trailing commas in JSON arrays and objects (e.g., [1,2,] becomes [1,2]) as part of the SimpleRepairStrategy. The repair logic detects comma tokens that appear before closing brackets or braces and removes them, producing valid JSON that conforms to the JSON specification which disallows trailing commas.

Automatically adds missing outermost braces or brackets to convert partial JSON fragments into valid JSON objects or arrays. For example, converts [1,2,3 to [1,2,3] or {"key":"value" to {"key":"value"}. This is implemented in SimpleRepairStrategy by detecting unclosed top-level delimiters and inserting the corresponding closing delimiter at the end of the input.

Fills missing values in JSON objects and arrays with null when a key is present but has no value, or when an array element is missing. For example, converts {"key":} to {"key":null} or [1,,3] to [1,null,3]. This is part of SimpleRepairStrategy and ensures that all keys have values and all array positions are filled, producing valid JSON that can be parsed without type errors.

Includes built-in JMH (Java Microbenchmark Harness) benchmarks via BenchmarkTests class that measure repair latency for different JSON complexity levels (simple objects, arrays with missing brackets, nested structures, unquoted keys). Benchmarks are executed as part of the test suite and generate detailed performance reports (benchmark_0.2.2.json) showing nanosecond-level timing for each repair operation, enabling developers to understand repair overhead and optimize for their use case.

Uses Maven as the build system with integrated ANTLR code generation plugin (maven-antlr4-plugin) that automatically generates parser and lexer classes from ANTLR grammar files during the build process. The pom.xml configuration manages dependencies (ANTLR runtime, JSON libraries, testing frameworks) and build phases, enabling reproducible builds and easy integration into Java projects via Maven Central repository.