JSON Toolkit

Guide de réparation JSON : sauver les sorties LLM cassées sans perdre la confiance

L’essentiel : Les sorties LLM enveloppées de balises markdown, truffées de virgules finales et de littéraux Python, sont rejetées par tout parseur strict — tout comme les configs éditées à la main sans guillemets. Ce guide trace la vraie frontière entre neuf classes d'erreurs réparables et quatre irréparables, explique pourquoi une machine à états bat les regex, et fournit une chaîne d'analyse prête pour la production avec jsonrepair et json-repair.

Intermédiaire~6 min de lecturePublié le 2026-11-08Mis à jour le 2026-11-08
Diagramme du pipeline de réparation JSON : décapage des balises, normalisation des guillemets, équilibrage des crochets, validation finale

Un parseur strict n'accorde rien à une entrée cassée : un message d'erreur, un numéro de ligne, et pas un seul octet de vos données. Le réparateur existe pour transformer « échec total » en « assez bon pour tourner » — mais ce qu'il comble n'est jamais qu'une meilleure supposition sur l'intention, pas une garantie de correction.

Un : d'où vient le JSON cassé

La réparation n'est pas magique : commencez donc par examiner l'entrée. Dans les projets réels, le JSON non standard provient de trois sources concentrées :

  1. Les sorties LLM. Les modèles de langage génèrent du texte token par token ; ils n'exécutent pas de sérialiseur JSON. Même en demandant « JSON uniquement », le modèle enveloppe la charge dans une balise ```json, ajoute « Voici vos données » devant, laisse traîner une virgule finale, ou atteint le plafond de tokens et s'arrête au milieu d'un objet.
  2. Le copier-coller depuis d'autres langages. Un objet JavaScript affiché via console.log embarque des apostrophes et des clés sans guillemets ; un dictionnaire Python s'imprime en True/False/None. Ces chaînes « ressemblant à du JSON » explosent au premier contact avec JSON.parse.
  3. Les configs JSON5/JSONC. Des fichiers comme tsconfig autorisent légitimement commentaires et virgules finales. Collez-en un dans un parseur strict et il rejette le fichier entier.

Les trois sources demandent des traitements différents, mais les réparateurs couvrent les trois — à condition que l'erreur figure dans leur liste déclarée de réparations possibles.

Deux : neuf classes d'erreurs qu'un réparateur corrige réellement

En combinant la documentation de la bibliothèque jsonrepair avec les listes de capacités publiées par les éditeurs d'outils, les erreurs réparables automatiquement se répartissent en neuf classes :

Classe Entrée cassée Résultat réparé
Virgule finale [1, 2, 3,] [1, 2, 3]
Apostrophes / guillemets typographiques {'a': 'b'}、{"a": "b"} {"a": "b"}
Clés sans guillemets {name: 'Ada'} {"name": "Ada"}
Commentaires {"a": 1 /* note */} {"a": 1}
Littéraux Python {"ok": True, "v": None} {"ok": true, "v": null}
Balises markdown ```json {...} ``` {...}
Virgules manquantes [1 2] [1, 2]
Crochets / guillemets non fermés {"a": [1, 2 {"a": [1, 2]}
JSONP / concaténation de chaînes cb({...})、"x" + "y" {...}、"xy"

Ce que ces neuf classes partagent : les données sont toutes là ; seul le syntaxe est cassé. Le réparateur ajuste ponctuation et emballages sans toucher une seule valeur. Quelques détails méritent une attention particulière :

  • Les nombres à zéro initial deviennent des chaînes. 007 est réparé en "007", pas en 7, pour ne pas perdre de chiffre. Si le champ est réellement un code textuel, c'est correct ; si c'est un vrai nombre, la décision vous appartient.
  • Les mots nus deviennent des chaînes. NaN ne peut être réparé en nombre — certaines implémentations émettent "NaN", d'autres null. Le comportement varie selon les bibliothèques ; testez la vôtre avant de l'intégrer à un pipeline.
  • Une entrée valide traverse la réparation intacte. Tout réparateur sérieux exécute d'abord un chemin rapide de parse strict. Le JSON valide n'entre jamais dans la logique de réparation : impossible de « réparer un bon document en mauvais ».

Trois : quatre choses qu'un réparateur ne peut pas réparer

La frontière de l'autre côté est tout aussi explicite. N'espérez pas de réparation pour :

  1. Les pages d'erreur HTML ou la pure prose. Aucune structure JSON dans l'entrée, et aucun outil ne peut créer des données à partir de rien.
  2. Des données syntaxiquement valides mais fausses. Une clé mal orthographiée, une valeur au mauvais endroit, un nombre stocké en chaîne — ce sont des problèmes sémantiques que chaque parseur, réparateurs compris, laisse passer sans broncher.
  3. Les données perdues à cause d'une troncature. L'achèvement peut transformer {"items": [{"id": 1}, {"na en JSON valide, mais la valeur de name ne reviendra jamais. Vous récupérez un objet « valide mais incomplet ». En production, vérifiez stopReason === "max_tokens" avant de décider d'achever ou de retenter.
  4. Les clés dupliquées et les structures ambiguës. Laquelle de deux clés identiques l'emporte dépend de l'implémentation du parseur. Les réparateurs responsables offrent un mode strict qui lance une erreur au lieu de choisir silencieusement.

Une phrase résume la frontière de confiance : la réparation est une meilleure supposition, pas une garantie de correction. Laisser passer un résultat de réparation non vérifié vers l'aval, c'est échanger une erreur de syntaxe bruyante contre une erreur de données silencieuse.

Quatre : deux écoles d'implémentation — une URL tranche le débat

Les réparateurs du marché viennent en deux saveurs, et l'écart se manifeste sur un type d'entrée précis.

L'école regex applique un chercher-remplacer global aux motifs cassés. Considérez cette entrée :

{"url": "http://example.com", 'note': 'fine'}

Une regex qui convertit les apostrophes en guillemets mâchera le contenu de l'URL ; une regex de nettoyage des commentaires qui supprime chaque // coupera http:// en deux. À l'intérieur d'une chaîne et à l'extérieur d'une structure, les caractères se ressemblent — la regex ne peut les distinguer.

L'école de la machine à états caractère par caractère suit un état d'analyse : dans une chaîne entre guillemets doubles, dans une chaîne entre apostrophes, dans un commentaire de ligne, dans un commentaire de bloc, ou en attente d'une valeur. En voyant ', elle demande d'abord « suis-je dans une chaîne ? » avant de décider de convertir ou d'ignorer. http://example.com se trouve dans une chaîne entre doubles guillemets, la machine à états sait donc que le // est une donnée, pas un commentaire, et le préserve. jsonrepair et json-healer appartiennent à cette école, et le mantra communautaire « un réparateur n'est pas un chercher-remplacer » désigne précisément cela.

L'ordre complet du pipeline de réparation (tel que divulgué par l'implémentation devkits) mérite aussi un regard : décaper les balises → normaliser les guillemets typographiques → extraire le premier bloc équilibré → retirer les commentaires → guilleter les clés nues → supprimer les virgules finales → convertir les littéraux → re-sérialiser avec JSON.stringify. Cette re-sérialisation finale est l'étape clé : quoi que fassent les étapes précédentes, la sortie est régénérée depuis le résultat analysé, donc tout parseur strict en aval peut la consommer.

Cinq : l'intégrer en code — une chaîne d'analyse séquentielle

Quand vous intégrez la réparation en code, l'ordre importe plus que le choix de la bibliothèque. En suivant les modèles publiés par json2toon et aijsonmedic, la séquence doit être : vérification de troncature → extraction de la plage JSON → parse strict → réparation de secours → validation par schéma.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Réparer une sortie tronquée laisse des données manquantes — retentez
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Extraire la plage JSON : le LLM peut bavarder avant et après
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // chemin rapide pour entrée valide
  } catch {
    return JSON.parse(jsonrepair(candidate));  // réparation de secours
  }
}

Côté Python, le paquet json-repair (plus de 4 700 étoiles) offre loads(), qui renvoie directement un objet :

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

Deux détails d'ingénierie :

  • Alignez vos piles. Si le frontend et le backend réparent tous les deux, choisissez des implémentations à sémantique partagée — le Python json-repair et son port TypeScript @yarmu/json-repair, ou jsonmend, dont les versions Python et JS passent le même corpus de conformité de 485 cas. Sinon, la même sortie se répare en A côté client et en B côté serveur, et le débogage devient misérable.
  • Activez le journal de réparation. @yarmu/json-repair avec logging: true renvoie un tableau de chaque opération de réparation. Une hausse soudaine du taux de réparation signifie généralement que le prompt ou la version du modèle a changé — un signal plus précoce que tout rapport d'erreur.

Une étape après la réparation est non négociable : la validation par schéma. Syntaxiquement valide ne signifie pas exploitable. Champs manquants, types erronés et clés inattendues sont tous attrapés par un schéma. L'approche des tests de contrat s'applique directement ici ; voir notre guide sur les tests de contrat JSON Schema.

Six : liste de prévention — la réparation la moins chère est celle dont on n'a pas besoin

La réparation est le filet de sécurité. Produire moins de JSON cassé à la source est la vraie victoire, par ordre de priorité :

  1. Structured Outputs (mode json_schema). Le décodage est contraint par le schéma, donc une virgule finale ne peut tout simplement pas être générée. Le mode strict d'OpenAI échoue à environ 0,1 %, au prix d'exigences dures comme additionalProperties: false.
  2. Mode JSON (json_object). Garantit seulement la validité syntaxique — pas la forme — et la troncature par limite de tokens survient toujours.
  3. Instructions explicites. Sur les endpoints sans mode JSON, écrire « pas de balises, pas de commentaires, pas de virgules finales, ne sortir que l'objet » réduit le taux d'erreurs de 70 à 80 %.
  4. Baisser la temperature, monter la limite de tokens. La première réduit la dérive vers la prose ; la seconde réduit les troncatures.
  5. Retenter avec l'erreur jointe. Quand la validation échoue, ajoutez la sortie cassée plus le « chemin JSON + message d'erreur » à la conversation et redemandez. Les modèles se corrigent généralement eux-mêmes avec une erreur précise.

En pratique, l'empilement « structured outputs + réparation de secours + validation par schéma » couvre pratiquement tous les scénarios.

Sept : répartir le travail — la conversion de dialecte n'est pas la réparation

Dans la boîte à outils de ce site, deux destinations couvrent des segments distincts de ce pipeline :

  • Les problèmes de dialecte (commentaires, apostrophes, virgules finales) vont droit au convertisseur JSON5. La conversion JSON5 ↔ JSON standard couvre exactement ces trois classes avec une sémantique explicite, sans devinette. Si l'entrée entière est un fichier JSONC/JSON5, la conversion est plus prévisible que la réparation. Pour les compromis des dialectes eux-mêmes, voir le guide JSON5 et JSONC.
  • Après réparation, passez le résultat par l'outil d'analyse JSON pour valider et formater, avec les erreurs localisées ligne et colonne, confirmant qu'un parseur strict accepte vraiment la sortie.
  • Les problèmes de classe bibliothèque (littéraux Python, achèvement de troncature, enveloppes JSONP, balises markdown) exigent encore jsonrepair / json-repair côté code — il n'existe pas de réparation équivalente en un clic dans le navigateur, car ces réparations impliquent d'inférer l'intention, et une bibliothèque locale en est un hôte plus sûr qu'un convertisseur universel.

Si ce que vous tenez est un message d'erreur plutôt que des données cassées, commencez par le guide de correction des erreurs d'analyse JSON pour traduire le message en coordonnées, puis décidez : édition à la main ou réparation.

FAQ

La réparation JSON corrompt-elle mes données ?

Pour les neuf classes réparables, seuls ponctuation et emballages changent — les valeurs restent intactes, et les //, virgules et accolades à l'intérieur des chaînes sont préservés par la machine à états. Mais l'achèvement de troncature donne des objets incomplets, les nombres à zéro initial deviennent des chaînes, et le traitement de NaN varie selon les bibliothèques. Vérifier les champs clés après réparation est obligatoire.

Quelle relation entre réparation et validation ?

La validation vous dit où l'entrée est illégale ; la réparation vous remet un document légal. Le flux fiable fait les deux : réparer d'abord, valider ensuite — le schéma attrape les types et champs requis, la vérification syntaxique confirme qu'un parseur strict accepte le résultat. Réparer sans valider, c'est échanger une erreur de syntaxe bruyante contre une erreur de données silencieuse.

Le LLM enveloppe toujours la sortie dans une balise ```json — que faire ?

À court terme, extrayez : prenez le texte du premier { ou [ jusqu'au dernier } ou ] et parsez-le ; un réparateur avec décapage de balises avalera aussi le message entier. À long terme, utilisez structured outputs ou une instruction explicite « pas de balises markdown » pour que la balise ne soit jamais générée.

jsonrepair ou json-repair — lequel choisir ?

Pour JavaScript, le paquet npm jsonrepair (il supporte un transform en flux) ; pour Python, json-repair de PyPI. Si les deux extrémités réparent, choisissez une paire à sémantique alignée — par exemple json-repair plus son port TS — pour que la même entrée se répare identiquement des deux côtés.

Les réparateurs gèrent-ils l'accents français et les guillemets typographiques ?

Oui. Les guillemets typographiques produits par les claviers français (« »), les espaces insécables et le BOM en tête de fichier figurent tous sur la liste standard de réparation ; les guillemets typographiques sont normalisés en guillemets droits. Passez le résultat dans un validateur une fois et c'est réglé.