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 même commentaires sont légaux, parce que la source est analysée par le même moteur que tout le reste. JSON n'est pas du JavaScript — c'est une grammaire bien plus petite et plus stricte (RFC 8259), et JSON.parse() applique chaque règle de cette grammaire sans repli. Il n'existe pas de JSON « à peu près correct » ; l'analyseur lit de gauche à droite et s'arrête net au premier jeton qui ne correspond pas à la grammaire à cette position.

C'est un choix de conception délibéré, pas une limitation : un analyseur JSON permissif accepterait silencieusement des documents subtilement différents selon les implémentations — exactement le problème d'interopérabilité que JSON a été inventé pour éviter. Le coût, c'est que les messages d'erreur sont laconiques et positionnels plutôt que sémantiques — 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) sont extrêmement courantes quand le JSON est tapé à la main ou copié-collé 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 est subtilement différente : V8 moderne reconnaît qu'un nom de propriété était attendu et signale `Expected property name or '}' in JSON at position 2`, au lieu d'incriminer directement l'identifiant nu. Dans tous les cas, la correction est mécanique — enveloppez 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

Un saut de ligne brut, une tabulation ou tout autre caractère de contrôle (n'importe quoi en dessous de U+0020) à l'intérieur d'une chaîne JSON est illégal — il doit être échappé en `\n`, `\t`, etc. Cela mord le plus souvent quand le JSON est généré en concaténant naïvement 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 au préalable.

{
  "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 réel au lieu d'un simple jeton. La correction consiste à échapper le caractère plutôt que de le laisser apparaître brut : `"line one\nline two"`.

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

Trois modes de défaillance plus discrets, à connaître par leur nom. Premièrement, les clés dupliquées dans un objet JSON ne provoquent aucune erreur d'analyse — `{ "id": 1, "id": 2 }` s'analyse avec succès, et JSON.parse conserve silencieusement la dernière occurrence (`id: 2`) en écartant la première. La RFC 8259 dit que les noms « devraient » être uniques mais n'impose pas aux analyseurs de rejeter les doublons : c'est un comportement conforme à la spécification, facile à manquer en revue, plutôt qu'un bogue de votre analyseur.

Deuxièmement, `NaN`, `Infinity` et `undefined` sont tous valides en JavaScript mais aucun n'est un jeton JSON valide — JSON n'a que `number`, pas les valeurs spéciales IEEE-754, et n'a pas du tout de concept 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). Si vous sérialisez depuis JavaScript, `JSON.stringify` convertit déjà `NaN`/`Infinity` en `null` et supprime entièrement les valeurs `undefined` — l'erreur signifie généralement que le JSON a été écrit à la main ou provient d'une source non-JS qui supposait la sémantique JS.

Troisièmement, une marque d'ordre d'octets UTF-8 (U+FEFF) au tout début d'un fichier — souvent ajoutée silencieusement par des éditeurs Windows ou certains outils Java/.NET lors d'un enregistrement en UTF-8 — casse `JSON.parse` quand le fichier est lu comme une chaîne brute, produisant `Unexpected token '\ufeff'... is not valid JSON` à la position 0. Notez que c'est spécifiquement un problème de `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 dans le cadre de ce décodage, donc les mêmes octets servis via HTTP et lus depuis le disque avec `fs.readFileSync(path, 'utf8')` peuvent se comporter différemment.

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 exacte que vous avez transmise, pas un numéro de ligne — Node (v20+) calcule et ajoute en plus un `(line X column Y)` par commodité, mais les runtimes et navigateurs plus anciens ne donnent que le décalage brut. Deux choses piègent les gens : la position signalée est l'endroit où l'analyseur a remarqué que la grammaire était cassée, ce qui, pour une virgule finale ou un crochet manquant, se situe souvent un jeton après votre erreur réelle ; et si vous avez mis le JSON en forme pour la lisibilité mais déboguez 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, la corriger à la main une fois la position localisée est plus rapide que n'importe quel outil — collez-la dans un validateur qui surligne le caractère exact plutôt que de compter les décalages manuellement. Pour un gros fichier avec plusieurs erreurs sans rapport, du JSON généré par un outil bogué en amont, ou du JSON passé par plusieurs rondes de copier-coller avec perte, la correction manuelle n'en vaut plus la peine. C'est le moment d'utiliser quelque chose d'automatisé : le JSON Validator de JsonForge localise chaque violation de schéma avec un chemin précis une fois que le document s'analyse au moins, et JSON Repair tente de corriger automatiquement les erreurs structurelles courantes (guillemets manquants, virgules finales, crochets déséquilibrés) quand l'entrée est trop abîmée pour être corrigée erreur par erreur.