fast_json_repair

A high-performance JSON repair library for Python, powered by Rust. This is a drop-in replacement for json_repair with significant performance improvements.

🙏 Attribution

This library is a Rust port of the excellent json_repair library created by Stefano Baccianella. The original Python implementation is a brilliant solution for fixing malformed JSON from Large Language Models (LLMs), and this port aims to bring the same functionality with improved performance.

All credit for the original concept, logic, and implementation goes to Stefano Baccianella. This Rust port maintains API compatibility with the original library while leveraging Rust's performance benefits.

If you find this library useful, please also consider starring the original json_repair repository.

Features

• 📦 Available on PyPI: pip install fast-json-repair
• 🚀 Rust Performance: Core repair logic implemented in Rust for maximum speed
• 🔧 Automatic Repair: Fixes common JSON errors automatically
• 🐍 Python Compatible: Works with Python 3.11-3.14
• 🔄 Drop-in Replacement: Compatible API with the original json_repair library
• ⚡ Fast JSON Parsing: Uses orjson for JSON parsing operations

Compatibility with Original json_repair

This is a drop-in replacement for the original json_repair library with the same API:

✅ Included:

• repair_json() - Main repair function with object, logging, formatting, and validation options
• loads() - Convenience function for loading broken JSON directly to Python objects
• json.dumps formatting arguments such as ensure_ascii, indent, sort_keys, and separators
• Common repair capabilities: quotes, literals, commas, brackets, comments, wrappers, escape sequences, and Unicode

❌ Not Included:

• File operations (load(), from_file()) - Use Python's built-in file handling + repair_json()
• CLI tool - Library-only implementation
• Streaming support - Not yet implemented

Key Differences:

• 🚀 30.5x geometric-mean speedup for malformed benchmark inputs
• 🔢 Unquoted numbers parsed as numbers (not strings)
• 📦 Uses orjson for high-performance JSON operations

Installation

Quick Install

pip install fast-json-repair

Build from Source

# Clone the repository
git clone https://github.com/Rusty-Ports/fast_json_repair.git
cd fast_json_repair

# Run the automated setup script
./setup.sh

# Clone the repository
git clone https://github.com/Rusty-Ports/fast_json_repair.git
cd fast_json_repair

# Option 1: Using uv (fast!)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync
maturin develop --release

# Option 2: Using pip
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install maturin orjson
maturin develop --release

Usage

from fast_json_repair import repair_json, loads

# Fix broken JSON
broken = "{'name': 'John', 'age': 30}"  # Single quotes
fixed = repair_json(broken)
print(fixed)  # {"name":"John","age":30}

# Parse directly to Python object
data = loads("{'key': 'value'}")
print(data)  # {'key': 'value'}

# Handle Unicode properly
text = "{'message': '你好世界'}"
result = repair_json(text, ensure_ascii=False)
print(result)  # {"message":"你好世界"}

# Format with indentation
formatted = repair_json("{'a': 1}", indent=2)

Inspect repairs

Pass logging=True to return the repaired object together with detailed repair events. Diagnostics are collected only on this opt-in path.

data, repairs = repair_json("{name: 'Ada',}", logging=True)

for repair in repairs:
    print(
        repair["type"],
        repair["line"],
        repair["column"],
        repair["context"],
    )

Each event contains a stable type, a human-readable text description, nearby source context, a zero-based UTF-8 byte position, and one-based line and column values. Valid JSON returns an empty repair list.

What It Repairs

Automatically fixes common JSON formatting issues:

API Reference

repair_json(json_string, **kwargs)

Repairs invalid JSON and returns valid JSON string.

Parameters:

• json_string (str): The potentially invalid JSON string to repair
• return_objects (bool): If True, return parsed Python object instead of JSON string
• skip_json_loads (bool): If True, skip initial validation for better performance
• logging (bool): If True, return the parsed object and detailed repair events
• stream_stable (bool): Accepted for API compatibility
• ensure_ascii (bool): If True, escape non-ASCII characters in output
• indent (int): Number of spaces for indentation (None for compact output)
• **kwargs: Additional arguments forwarded to json.dumps

Returns:

• str or object: Repaired JSON string or parsed Python object
• tuple: Parsed Python object and repair event list when logging=True

loads(json_string, **kwargs)

Repairs and parses invalid JSON string to Python object.

Parameters:

• json_string (str): The potentially invalid JSON string to repair and parse
• **kwargs: Additional arguments passed to repair_json

Returns:

• object: The parsed Python object

Performance

This Rust-based implementation provides significant performance improvements over the pure Python original.

Fast Path Optimization

The library automatically uses the fastest path when possible:

Fast Path (uses orjson and Rust ASCII escaping):

• Valid JSON input
• indent is either None (compact) or 2

Fallback Path (uses stdlib json):

• Arbitrary-precision integers outside orjson's 64-bit range
• Custom json.dumps options or indentation values other than None or 2

Repair Path (uses Rust implementation):

• Any invalid JSON that needs repair
• Always respects ensure_ascii and indent settings

Benchmark Results

Version 0.2.2 was measured across 18 deterministic workloads, with 10 timed runs and 3 warmups per case. Validation occurs outside the timed region.

Performance Advantages

• Malformed inputs: 30.5x geometric-mean speedup
• Valid inputs: 2.9x geometric-mean speedup
• All cases: 10.8x geometric-mean speedup
• Deep formatting: A 100K payload took 0.334 ms at depth 1 and 0.433 ms at depth 900
• Lower peak memory: The lexer streams over UTF-8 and the formatter writes into one output buffer

Run python benchmark.py to test performance on your system. See PERFORMANCE.md for detailed analysis.

AWS Deployment

Works seamlessly on AWS with pre-built wheels for all architectures:

• x86_64 - Standard EC2 instances (t2, t3, m5, c5, etc.)
• ARM64/aarch64 - Graviton instances (t4g, m6g, c6g, etc.)

# Install on any AWS instance - pip auto-selects the correct wheel
pip install fast-json-repair

For Lambda layers and cross-compilation, see DEPLOYMENT.md.

Development

Quick Reference

Quick Setup

# Automated setup (recommended)
./setup.sh

# Or manually with uv
uv venv && source .venv/bin/activate
uv sync
maturin develop

VS Code Integration

This project includes a complete VS Code workspace configuration:

Getting Started:

1. Open the project folder in VS Code
2. Install recommended extensions (you'll see a prompt)
3. The Python interpreter will auto-detect .venv
4. Press Cmd+Shift+P → "Tasks: Run Task" to see all available commands

Available Tasks:

• 🔧 Build Tasks: Debug build, release build, wheels, cross-platform builds
• 🧪 Test Tasks: Run all tests, quick tests, coverage reports
• ⚡ Benchmark Tasks: Full benchmarks, quick benchmarks, save results
• 🦀 Rust Tasks: Check, clippy, format, clean
• 🐍 Python Tasks: Format (black), sort imports (isort), lint (ruff)
• 🚢 Workflows: Full check (build+test+benchmark), release prep, quality checks

Debugging:

• Press F5 to debug Python tests
• Set breakpoints in Python code
• Use "Debug: Select and Start Debugging" for specific configs

Common Commands

See the Quick Reference table above for the most common tasks. Additional commands:

# Code quality
black .                # Format Python code
isort .                # Sort Python imports
ruff check .           # Lint Python code

# Cross-platform builds (requires zig)
maturin build --release --target x86_64-unknown-linux-gnu --zig
maturin build --release --target aarch64-unknown-linux-gnu --zig
maturin build --release --target universal2-apple-darwin

Project Structure

fast_json_repair/
├── src/
│   └── lib.rs              # Rust implementation (core repair logic)
├── python/
│   └── fast_json_repair/
│       └── __init__.py     # Python API wrapper
├── tests/
│   └── test_all.py         # Python test suite
├── benchmark.py            # Performance benchmarks
├── pyproject.toml          # Python package configuration
├── Cargo.toml              # Rust package configuration
└── .vscode/                # VS Code workspace settings (local)
    ├── settings.json       # Python/Rust interpreter & formatting
    ├── tasks.json          # Build/test/benchmark tasks
    ├── launch.json         # Debug configurations
    └── extensions.json     # Recommended extensions

Typical Workflow

1. Make Changes - Edit Rust (src/) or Python (python/) code
2. Rebuild - maturin develop or VS Code task 🔧 Build: Development
3. Test - pytest tests/ -v or VS Code task 🧪 Test: Python (All)
4. Benchmark - python benchmark.py or VS Code task ⚡ Benchmark: Run Full Suite
5. Release - maturin build --release when ready to publish

License

MIT License (same as original json_repair)

Credits & Acknowledgments

Original Author

• Stefano Baccianella - Creator of the original json_repair library
  • Original concept and algorithm design
  • Python implementation that this library is based on
  • Comprehensive test cases and edge case handling

This Rust Port

• Performance optimization through Rust implementation
• Maintains full API compatibility with the original
• Uses PyO3 for Python bindings
• Uses orjson for fast JSON parsing

Special Thanks

A huge thank you to Stefano Baccianella for creating json_repair and making it open source. This library wouldn't exist without the original brilliant implementation that has helped countless developers handle malformed JSON from LLMs.

If you appreciate this performance-focused port, please also show support for the original json_repair project that made it all possible.