JSON Repair

Warnings

• gotcha The `schema_repair_mode='salvage'` option, introduced in v0.58.0, prioritizes data recovery but might yield an output that is not fully compliant with the provided JSON schema. There have been past regressions (fixed in v0.58.4) where `salvage` mode repaired less aggressively than `standard` mode.
  Fix: Carefully review the output when using `schema_repair_mode='salvage'`. Consider if `standard` mode or manual post-processing is more appropriate for strict schema adherence. Always test with representative malformed inputs.
• breaking Starting from v0.57.1, valid JSON input that does not conform to an optionally provided JSON schema may be *coerced* to match the schema's types (e.g., a string '1' might become an integer 1). This can alter data types in ways that might be unexpected if strict validation without coercion was desired.
  Fix: Be aware of potential type coercions when providing a `schema` parameter. If strict validation without modification is needed, consider validating the output separately or using an older version if possible, though this is not recommended. The library's focus is on repair and usability.
• gotcha By default, `json-repair` first attempts to parse the input using Python's standard `json.loads()`. Only if this fails does it proceed with its repair logic. Explicitly wrapping `json.loads()` in a `try...except` block before calling `json_repair.repair_json()` is redundant and an anti-pattern.
  Fix: Simply call `json_repair.repair_json()` or `json_repair.loads()`. If you are certain the input is invalid and want to skip the initial `json.loads()` attempt for performance reasons, pass `skip_json_loads=True`.
• gotcha The `strict=True` parameter changes the repair behavior to be more validation-oriented. In strict mode, the parser raises a `ValueError` for structural issues like duplicate keys, missing separators, or multiple top-level elements, rather than attempting to fix them. This results in less aggressive repair.
  Fix: Use `strict=True` when you need stricter validation and clear error messages for structural problems, accepting that some malformed JSON that would otherwise be repaired will instead raise an error. For maximum repair capability, omit `strict=True` (default is `False`).
• gotcha Versions prior to v0.58.5 had significantly lower parser performance, especially for common JSON strings. v0.58.5 introduced a 60% improvement.
  Fix: Upgrade to version 0.58.5 or newer for substantial performance gains when repairing JSON.

Install

• pip install json-repair Install stable version

Imports

• repair_json

  from json_repair import repair_json

• loads

  from json_repair import loads

  The primary repair function is `repair_json`. `loads` is a convenient drop-in replacement for `json.loads` that includes repair logic. Directly calling a non-existent `repair_json_string` method is a common typo.

Quickstart

The quickstart demonstrates repairing a malformed JSON string using both `repair_json` to get a valid string and `loads` for direct parsing into a Python object.

from json_repair import repair_json, loads
import json

broken_json_string = """{ 
  'name': 'Alice', 
  age: 30, 
  'isStudent': True,
  'hobbies': ['reading', 'gaming',],
}"""

# Using repair_json to get a fixed JSON string
repaired_string = repair_json(broken_json_string)
print(f"Repaired string: {repaired_string}")
parsed_data = json.loads(repaired_string)
print(f"Parsed data (using json.loads): {parsed_data}")

# Using loads for direct parsing to Python object
# This method already includes the repair logic internally
parsed_data_direct = loads(broken_json_string)
print(f"Parsed data (using json_repair.loads): {parsed_data_direct}")