json_repair : réparer le JSON cassé à la sortie des modèles et des API
Repair malformed JSON from LLMs, APIs, logs, and user input in Python.
En bref
- De quoi s’agit-il ?
- Une bibliothèque Python qui remplace json.loads() quand l'entrée n'est plus tout à fait du JSON. Le README annonce la réparation des virgules, guillemets et accolades manquants, mais aussi un mode strict par défaut qu'il faut connaître avant de l'intégrer.
- À qui s’adresse-t-il ?
- Adoptez json_repair si vous consommez du JSON produit par un LLM ou un tiers non fiable et que vous acceptez qu'une entrée illisible devienne une chaîne vide plutôt qu'une exception. Ne l'utilisez pas comme couche de sécurité sur une entrée hostile, ni comme parseur de remplacement pour valider un format.
- Puis-je l’utiliser commercialement ?
- Oui. MIT est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 6 jours.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Le problème concret : du JSON presque valide
Un modèle de langage qui doit renvoyer une structure de données le fait rarement avec une rigueur de compilateur. Il oublie une virgule, laisse une accolade ouverte, entoure une valeur de parenthèses à la Python, glisse une phrase avant l'objet. Le README le formule sans détour : certains LLM sont un peu approximatifs et ajoutent parfois des mots dans la sortie, parce que c'est ce que fait un LLM. Le même constat vaut pour une API qui a changé de schéma, un journal applicatif tronqué en fin de ligne, ou un champ rempli par un utilisateur.
La réaction habituelle est un try/except autour de json.loads() avec un repli maison. json_repair vise exactement cet espace : fournir un remplaçant direct de json.loads() et json.load() qui tente d'abord le parseur standard, puis bascule sur un parseur tolérant. La cible est claire : développeurs Python 3.10 et supérieur qui traitent des sorties de modèles, des réponses d'API ou des saisies utilisateur et ne peuvent pas se permettre de perdre l'objet entier à cause d'une virgule.
Deux parseurs derrière une seule fonction
Le mécanisme central tient en une phrase du README : par défaut, json_repair essaie d'abord le chargeur JSON de la bibliothèque standard et ne recourt au parseur de réparation que si l'analyse stricte échoue. Autrement dit, json_repair.loads() encapsule json.loads() et n'active la tolérance qu'en cas d'échec. C'est ce qui permet de l'appeler sans condition, sans branche conditionnelle dans le code appelant.
Le README signale explicitement un antipattern répandu : envelopper json_repair.loads() dans un try/except json.JSONDecodeError pour retomber sur la bibliothèque. C'est redondant, puisque la vérification stricte est déjà faite en interne. Le flux normal décrit par la documentation est donc : tenter json.loads(), retourner l'objet si ça passe, lancer le parseur de réparation sinon. Un appel suffit.
Ce que le parseur tolérant accepte, d'après la liste des cas pris en charge : guillemets manquants, virgules mal placées, caractères non échappés, paires clé-valeur incomplètes, valeurs true, false et null mal formatées, commentaires et texte parasite. Les séquences entre parenthèses séparées par des virgules deviennent des tableaux JSON, tandis qu'une valeur unique entre parenthèses reste un scalaire. Les valeurs true, false, null et None sont reconnues sans tenir compte de la casse à l'intérieur des tableaux, des objets et des tuples. Les champs vides sont complétés par des valeurs par défaut comme une chaîne vide ou null.
Installation et clés de configuration
L'installation se fait par pip :
pip install json-repair
L'usage le plus direct remplace json.loads() :
import json_repair decoded_object = json_repair.loads(json_string)
La variante explicite existe aussi, avec repair_json() et son paramètre return_objects :
import json_repair decoded_object = json_repair.repair_json(json_string, return_objects=True)
Pour un fichier, deux entrées sont documentées. json_repair.load() prend un descripteur de fichier ouvert en binaire et sert de remplaçant à json.load(). json_repair.from_file() prend directement le chemin. Le README précise que les exceptions liées aux entrées-sorties ne sont pas interceptées : OSError et IOError restent à votre charge.
Deux paramètres méritent une lecture attentive. ensure_ascii=False est nécessaire pour préserver les caractères non latins : sans lui, repair_json("{'test_chinese_ascii':'统一码'}") renvoie la version échappée en \u7edf\u4e00\u7801, avec lui la chaîne reste lisible. skip_json_loads=True saute la validation stricte et va directement au parseur de réparation, ce que le README réserve aux entrées dont on sait déjà qu'elles sont invalides. Enfin, repair_json accepte et transmet tous les paramètres de json.dumps, indent compris.
Le cas où la réparation devient une perte silencieuse
La limite la plus importante est énoncée dans le README lui-même : si la chaîne est très cassée, repair_json renvoie une chaîne vide. Il n'y a pas d'exception, pas de signal d'échec, juste une valeur vide. Pour un pipeline qui journalise les erreurs de parsing, c'est un changement de contrat : le mode d'échec passe de l'exception au résultat vide, et un appelant qui ne vérifie pas la sortie traitera une chaîne vide comme une donnée valide.
Cette tolérance a un second effet, moins visible. Un parseur qui complète les champs manquants par des valeurs par défaut produit un objet qui a l'air correct. Si le modèle a omis un champ parce qu'il n'avait pas l'information, la réparation masque l'omission derrière un null ou une chaîne vide. La structure survit, le sens peut avoir disparu. C'est un compromis assumé par le projet, pas un défaut d'implémentation, mais il déplace la responsabilité de la validation vers l'appelant.
Autre point à ne pas confondre : réparer n'est pas sécuriser. Le README ne présente nulle part json_repair comme un durcissement face à une entrée hostile, et la tolérance accrue du parseur ne le qualifie pas pour ce rôle. Pour une entrée non fiable au sens de la sécurité, ce n'est pas le bon outil.
Face à un parseur tolérant classique
L'alternative la plus directe est le repli manuel sur json.loads() avec un nettoyage par expressions régulières : supprimer les virgules finales, retirer le texte avant la première accolade, fermer les crochets ouverts. Cette approche reste viable quand les erreurs sont peu nombreuses et connues à l'avance. Elle se distingue de json_repair sur un point précis : le nettoyage par expressions régulières est une transformation appliquée à l'aveugle, alors que le parseur de json_repair reconstruit une structure en suivant la grammaire JSON et complète ce qui manque. Le README mentionne d'ailleurs que l'auteur a cherché un paquet Python léger capable de régler ce problème de façon fiable sans le trouver, ce qui situe le projet par rapport à cette catégorie d'outils plutôt qu'à un parseur strict.
Le second point de comparaison est interne au projet : utiliser json_repair en repli systématique après un json.loads() échoué, plutôt que de l'appeler directement. La différence n'est pas dans le résultat mais dans le coût, puisque l'appel direct refait la validation stricte en interne. Le README qualifie ce double appel de gaspillage.
Versionnage et coût de maintenance
Le rythme de publication est soutenu : trois versions en août 2026, v0.63.2, v0.63.3 et v0.63.4, la plus récente datée du 25 août, pour un dernier push sur main au 3 septembre 2026. Le numéro de version reste en 0.x, ce qui signifie que la stabilité de l'API n'est pas garantie par convention. Un projet qui épingle json_repair sans borne supérieure s'expose à des changements lors des mises à jour.
La licence est MIT, ce qui autorise l'usage commercial et la modification avec conservation de l'avis de licence. Le README signale que la bibliothèque est maintenue comme projet annexe et invite à sponsoriser son développement. C'est une information de maintenance, pas une garantie de continuité : un projet annexe dépend d'une seule personne pour l'essentiel. Les sponsors premium cités dans le README n'ont aucun effet sur les termes de la licence MIT. Ce paragraphe décrit la licence telle qu'elle est déclarée dans le dépôt et ne constitue pas un avis juridique.
Ce qu'il faut vérifier avant d'adopter
Le README décrit un cas d'usage bien délimité : des entrées dont on sait qu'elles sont presque du JSON, produites par un modèle, une API ou un utilisateur, dans un contexte où perdre l'objet entier coûte plus cher qu'accepter une réparation approximative. Si votre entrée est déjà stricte, json_repair ne fait que retomber sur json.loads() après une vérification supplémentaire, sans bénéfice.
Deux vérifications concrètes avant l'intégration. D'abord, cherchez dans votre code le motif try/except json.JSONDecodeError autour de json_repair.loads() : s'il est présent, supprimez-le, la vérification stricte est déjà faite en interne. Ensuite, si vos données contiennent du chinois, du japonais ou du coréen, passez ensure_ascii=False, sinon vous récupérerez des séquences \u échappées là où vous attendiez du texte lisible. Pour les entrées dont vous savez déjà qu'elles sont invalides, skip_json_loads=True évite la validation préalable, mais le README le réserve explicitement à ce cas.
Conclusion éditoriale
Adoptez json_repair si vous consommez du JSON produit par un LLM ou un tiers non fiable et que vous acceptez qu'une entrée illisible devienne une chaîne vide plutôt qu'une exception. Ne l'utilisez pas comme couche de sécurité sur une entrée hostile, ni comme parseur de remplacement pour valider un format. Avant de l'intégrer, vérifiez deux choses dans votre code : que vous ne réimplémentez pas le try/except json.loads() que la bibliothèque fait déjà, et que vous passez ensure_ascii=False si vos données contiennent du chinois, du japonais ou du coréen.
Notes de la communauté