json-repair: parsing what a language model meant to say

Zero dependencies, provable from the module file

The zero-dependency claim is the kind that is easy to make and easy to check, and here the module file settles it. There is no dependency block at all. The module definition consists of the module path and a single Go version directive, with no require section and no indirect list, which means the library is built entirely on the standard library. That matters more than it does for a typical utility, because this package sits in the middle of a request path where every transitive dependency is a supply chain decision you inherit. The implementation shape backs it up. Excluding the command line directory and the images, the whole library is four source files and their tests: one for the repair routine, one for normalization, one for the options surface, and one for schema handling. A release configuration sits at the root for producing binaries. For a parsing library, that is an unusually small footprint to audit.

The contract is that it always returns a string

The design decision that shapes everything is that repair never fails in the ordinary sense. The stated promise is that the tool always gives back a string result rather than an error, which inverts the usual parser contract. Most parsers return an error precisely so the caller can decide, and here the caller is assumed to be a pipeline that received output from a model and has no useful recovery path other than trying to interpret it anyway. Two entry points reflect that. One returns a repaired string and is used where you want to handle problems. The other is a short form for contexts where error handling is not appropriate, and the documentation names the two intended situations directly: command pipes, where there is nobody to return an error to, and trusted environments where failure is not a concern. The cost of the always-succeed contract is that it cannot tell you when the input was hopeless, which is a tradeoff worth naming before you adopt it.

The damage list is specific to model output

The catalogue of what it fixes is the best evidence of what problem this was written for, because the cases are not generic malformed JSON, they are the specific mistakes a language model makes. The list includes single-quoted strings where double quotes belong, bare uppercase literals where JSON requires lowercase ones, unquoted values in a key position, and a second colon inside a pair so that one key carries two values. It includes unclosed arrays and objects truncated mid-string, a bare bracket on its own, extra line breaks scattered inside an array, and trailing commas before a closing brace. Two entries are especially telling. One is a string containing link syntax with an unclosed bracket, which is what happens when a model inlines markdown. The other appears in the usage example itself, where the broken input is wrapped in a markdown code fence. Models emit those fences as text, so a repairer that ignored them would return something that still does not parse.

An options API appears when you need the value

The simple entry points return a compact string, and the documentation is careful to say that this behaviour is unchanged rather than promising more. A second API exists for callers who need the parsed value or want to see what happened. It takes the input and an options structure, and returns a result carrying three things: the parsed Go value, the compact repaired JSON, and a log of the repair actions, which is populated when logging is switched on. The zero value of the options structure is the normal repair path, which is a good design choice since the advanced surface costs nothing if you ignore it. Beyond logging, the options cover a strict mode, a stable streaming mode, a way to skip JSON validation, and schema-guided repair. There is also a shorter form for the common case of wanting only the parsed value, and separate entry points for reader and file input so that a stream does not have to be slurped into memory first.

Schema-guided repair goes past syntax

Everything described so far works on structure alone, which is sufficient for the damage models produce and insufficient when you know what the answer was supposed to look like. Schema-guided repair closes that gap by accepting a JSON Schema object or a boolean schema and repairing against it. The supported vocabulary is wide: object, array, and scalar types, required properties, defaults, enums and constants, item and additional-item rules, pattern properties and additional properties, the three composition keywords, local references, common string and numeric constraints, and containers holding nested JSON strings. There are two modes, and the distinction is the interesting part. The standard mode uses the schema to inform a repair. The salvage mode goes further, able to drop invalid entries from an array and to recover top-level fragments that match the schema when the surrounding structure is unusable. That is a more aggressive promise than most repair libraries make, and it is the mode to be careful with when the input is not actually a truncation.

The Python API did not survive the port

The project was converted from another language, and the documentation is unusually direct about what that conversion cost. The Go implementation keeps Unicode output by default. What it does not carry over is specified just as plainly: validation models defined with a Python type-hint library, and the keyword arguments specific to Python's serialiser. In other words, this is not a drop-in replacement for the original Python package. A caller migrating across gets the repair behaviour and loses the typed model layer, which for anyone using those models to describe expected output is the larger half of the library's surface. The roadmap records the conversion as complete, along with a minimum Go version, the test suite, command line support, a workflow and a published action, a package manager tap, and separate items for full-width character detection and smart quote handling. So the port was scoped deliberately rather than as a mechanical translation, and the trade-off was made knowingly.

A CLI, a tap, and a version still below one

The command line side exists because the library's contract implies a pipe use case, and the documented workflow reflects that:

brew install realalexandreai/tap-jsonrepair/jsonrepair

# from raw string
jsonrepair -i "{'employees':['John', 'Anna', "
# output: {"employees":["John","Anna","Peter"]}

# from file
jsonrepair -f <json-file>.json

An input flag takes a raw string and a file flag takes a path, which is the minimum surface for both shapes of use. Binaries are also published as release artefacts, and the release configuration at the repository root is what produces them. Two things to keep in mind. The documentation states that the existing flags and output behaviour are unchanged from before the port, which is reassuring for anyone with scripts but also means the command line has not been reconsidered since the rewrite. And the version is still in the zero point series, with the newest tagged build in September 2026, so the project has not yet declared a stable interface. The licence is a copyleft one, which is worth noting before it reaches a closed-source dependency tree.

Editorial conclusion

json-repair suits a Go service that has to accept model output as-is, since the always-returns-a-string contract is the right default for a pipeline that cannot afford to fail on a stray quote. It is a poor fit as a validator, because a repairer that always produces output will also produce output for input that was never JSON, and it is a poor fit if you are migrating from the Python original, since the Python-specific model and serialisation surface was deliberately dropped in the port. Before relying on it, turn on logging for a sample of real failures and read what it changed, because a silent repair that fixes structure while changing your data is the failure mode worth watching for.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. RealAlexandreAI/json-repair on GitHub
5. Releases