Erreurs d'analyse JSON courantes et comment les corriger

Pourquoi JSON.parse lève une erreur au lieu de deviner

Les littéraux d'objets JavaScript sont tolérants : clés non citées, virgules finales, chaînes entre apostrophes et commentaires y sont légaux, parce que le moteur analyse ce code comme n'importe quel autre. JSON est une grammaire bien plus petite et plus stricte (RFC 8259), et JSON.parse() applique chacune de ses règles sans repli. L'analyseur lit de gauche à droite et s'arrête au premier jeton qui ne correspond pas à la grammaire à cette position.

Les concepteurs l'ont voulu ainsi. Un analyseur JSON permissif accepterait des documents légèrement différents selon les implémentations, exactement le problème d'interopérabilité que JSON voulait éviter. En contrepartie, les messages d'erreur sont laconiques et ne donnent qu'une position. L'analyseur vous dit où la grammaire s'est brisée, pas ce que vous vouliez écrire.

Virgules finales

L'erreur JSON la plus courante est une virgule finale héritée de l'édition d'un littéral d'objet JavaScript (où elle est légale) en oubliant qu'elle ne l'est pas en JSON.

{
  "name": "Alice",
  "roles": ["admin", "editor"],
}

V8 rejette ceci à l'accolade fermante, pas à la virgule, car la virgule elle-même est une grammaire valide jusqu'à ce que l'analyseur s'attende à une autre propriété et trouve `}` à la place. Selon votre version de Node/Chrome, vous verrez quelque chose comme `Unexpected token '}', "...editor"],\n}"... is not valid JSON` (V8 récent, avec un extrait) ou l'ancien, plus laconique `Unexpected token } in JSON at position 47`. Dans tous les cas, la correction est la même : supprimez la virgule avant le crochet ou l'accolade fermant.

Apostrophes et clés non citées

JSON exige des guillemets doubles pour chaque chaîne et chaque clé, sans exception. Les chaînes entre apostrophes et les clés nues (non citées) reviennent sans cesse quand quelqu'un tape du JSON à la main ou le copie depuis du code JavaScript.

{ 'name': 'Alice' }
{ name: "Alice" }

Une apostrophe ouvrante produit quelque chose comme `Unexpected token ''', "{ 'name'"... is not valid JSON`. Une clé non citée donne un autre message : V8 moderne sait qu'il attendait un nom de propriété et signale `Expected property name or '}' in JSON at position 2` sans nommer l'identifiant nu. Dans les deux cas, la correction est mécanique : entourez chaque clé et chaque valeur de chaîne de guillemets doubles.

Sauts de ligne et caractères de contrôle non échappés dans les chaînes

JSON interdit un saut de ligne brut, une tabulation ou tout autre caractère de contrôle (tout ce qui est en dessous de U+0020) dans une chaîne. Échappez-le en `\n`, `\t`, etc. Le problème surgit surtout quand du code construit du JSON en concaténant une valeur multi-lignes (un message de log, un extrait de code, un commentaire d'utilisateur) dans un littéral de chaîne sans l'échapper.

{
  "message": "line one
line two"
}

Cela produit `SyntaxError: Bad control character in string literal in JSON at position 21`, une des rares erreurs JSON qui nomme le problème plutôt qu'un jeton. Échappez le caractère au lieu de le laisser brut : `"line one\nline two"`.

Clés dupliquées, NaN/Infinity/undefined et caractères BOM

Trois modes de défaillance plus discrets méritent un nom. D'abord, les clés dupliquées dans un objet JSON ne provoquent aucune erreur d'analyse. `{ "id": 1, "id": 2 }` s'analyse sans problème, et JSON.parse garde la dernière occurrence (`id: 2`) et écarte la première sans prévenir. La RFC 8259 dit que les noms « devraient » être uniques mais n'impose pas aux analyseurs de rejeter les doublons, donc votre analyseur respecte la spécification, et ce bogue échappe facilement aux relecteurs.

Ensuite, `NaN`, `Infinity` et `undefined` sont valides en JavaScript mais ne sont pas des jetons JSON. JSON a `number` sans les valeurs spéciales IEEE-754, et n'a pas d'`undefined` (seulement `null`). `{ "value": NaN }` lève `Unexpected token 'N', ..."value":NaN}"... is not valid JSON` (ou `Unexpected token N in JSON at position 10` sur les moteurs plus anciens). `JSON.stringify` convertit `NaN`/`Infinity` en `null` et supprime les valeurs `undefined`, donc cette erreur signifie en général que quelqu'un a écrit le JSON à la main ou qu'une source non-JS a supposé la sémantique JS.

Enfin, une marque d'ordre d'octets UTF-8 (U+FEFF) au début d'un fichier casse `JSON.parse` quand vous lisez le fichier comme une chaîne brute, et produit `Unexpected token '\ufeff'... is not valid JSON` à la position 0. Les éditeurs Windows et certains outils Java/.NET l'ajoutent en enregistrant en UTF-8. Le problème touche `JSON.parse` sur une chaîne : `Response.json()` de l'API Fetch décode le texte UTF-8 et retire un BOM en tête pendant le décodage, donc les mêmes octets peuvent se comporter différemment via HTTP et lus depuis le disque avec `fs.readFileSync(path, 'utf8')`.

Lire la position, et quand utiliser un outil de réparation

La `position` dans une erreur JSON.parse est un décalage de caractères indexé à zéro dans la chaîne que vous avez transmise, pas un numéro de ligne. Node (v20+) ajoute aussi un `(line X column Y)`, mais les runtimes et navigateurs plus anciens ne donnent que le décalage brut. Deux choses piègent les gens. La position marque l'endroit où l'analyseur a remarqué la grammaire cassée, et pour une virgule finale ou un crochet manquant, cet endroit se trouve souvent un jeton après votre erreur. Et si vous avez mis le JSON en forme pour le lire tout en déboguant la chaîne minifiée d'origine, les décalages ne correspondront pas à ce que vous voyez à l'écran.

Pour une erreur de syntaxe ponctuelle dans un document court, corrigez-la à la main une fois la position trouvée. Collez-le dans un validateur qui surligne le caractère au lieu de compter les décalages. Pour un gros fichier avec plusieurs erreurs sans rapport, du JSON produit par un outil bogué en amont, ou du JSON abîmé par plusieurs rondes de copier-coller, la correction manuelle coûte trop de temps. Passez alors à l'automatisation. Le JSON Validator de JsonForge localise chaque violation de schéma avec un chemin précis dès que le document s'analyse, et JSON Repair corrige les erreurs structurelles courantes (guillemets manquants, virgules finales, crochets déséquilibrés) quand l'entrée est trop abîmée pour une correction erreur par erreur.