@isdk/json-repair

> 【English|中文】
---

A powerful, schema-guided JSON repair library specifically designed to fix "broken" JSON generated by LLMs (Large Language Models).


🚀 Why this library?

LLMs often output JSON that is syntactically invalid or semantically "noisy". Common issues include:

- Missing quotes around keys or values.
- Unescaped quotes inside strings (e.g., "a"b").
- Missing commas or closing braces.
- Natural language mixed into values (e.g., "age": "about 30 years old").
- Implicit structures (e.g., an array of objects without curly braces).

Standard json-repair libraries only fix syntax. @isdk/json-repair uses your JSON Schema as a map to intelligently navigate, repair, and coerce the output into valid, structured data.

✨ Key Features

- Schema-Guided Repair: Uses your Schema to resolve ambiguities (e.g., knowing if a colon marks a new key or is part of a string).
- Greedy String Capture: Intelligently captures unquoted or broken strings until the next valid Schema key.
- Balanced Delimiter Tracking: Correctly handles structural markers (commas, colons) inside parentheses, brackets, or braces within DSL-like strings (e.g., @func(a, b)).
- The "Parity Rule": Solves nested quote ambiguity (e.g., correctly distinguishing between "A" OR "B" and "a"b").
- Semantic Coercion:
- Fuzzy Enum Matching: Matches "Processing!" to "processing" if defined in Schema enums.
- Noisy Number Extraction: Extracts 1200.5 from "Approx. 1,200.50 USD".
- Boolean Variants: Recognizes yes/no, on/off, 1/0, 确定/取消 as booleans.
- Implicit Structure Support: Automatically repairs missing braces in objects and arrays.
- Performance: Support for reusing SchemaWalker instances for high-throughput batch processing.

📦 Installation

``bash
npm install @isdk/json-repair @apidevtools/json-schema-ref-parser


or


pnpm add @isdk/json-repair @apidevtools/json-schema-ref-parser
`

🛠 Usage

$3

This is the most powerful way to use the library. Providing a schema enables advanced features like semantic coercion, greedy capture, and accurate disambiguation.

`typescript
import { jsonRepair } from '@isdk/json-repair';

const schema = {
type: 'object',
properties: {
query: { type: 'string' },
status: { enum: ['success', 'error'] }
}
};

const brokenJson = '{ query: "python" OR "js", status: Success! }';

const result = await jsonRepair(brokenJson, schema);
console.log(result);
// Output: { query: '"python" OR "js"', status: 'success' }
`

$3

For basic syntax repair where schema guidance isn't required:

`typescript
import { jsonRepair } from '@isdk/json-repair';

const result = await jsonRepair('{ name: John, age: 30 }');
console.log(result); // { name: 'John', age: 30 }
`

$3

For better performance when processing many items with the same schema:

`typescript
import { jsonRepair, SchemaWalker } from '@isdk/json-repair';

const walker = await SchemaWalker.create(mySchema);

for (const item of brokenItems) {
const result = await jsonRepair(item, walker);
// ...
}
`

⚠️ Known Limitations & Disambiguation

- The "Parity Rule": When a string is wrapped in quotes and contains internal quotes, we count the internal ones.
- Odd count (e.g., "a"b"): We assume the outer quotes are delimiters -> a"b.
- Even count (e.g., "A" OR "B"): We assume the outer quotes are part of the expression -> "A" OR "B".
- Limitation: Highly unusual patterns like "a"b"c" might remain ambiguous.
- Markdown Blocks: This library focuses on the JSON content. Please strip `json ...`` markers before passing the string if your LLM includes them.

📄 License

MIT © Riceball LEE