Valider du JSON

N’importe quoi sait vous dire qu’un JSON n’est pas valide ; une console de navigateur le fait en une ligne. Ce qui vaut la peine d’être obtenu, c’est où, et tous les analyseurs sont mauvais pour le dire de façon exploitable. « Unexpected token } » dans un fichier de quatre cents lignes est un constat évident sans adresse.

Cette page indique donc la ligne et la colonne, affiche cette ligne, et place un repère sous le caractère. En pratique cela suffit à voir le problème sans ouvrir le fichier : une virgule manquante saute aux yeux dès qu’on voit la ligne du dessus, et le repère se trouve presque toujours sur le token qui suit ce que vous avez oublié.

C’est la chose la plus utile à savoir pour lire une erreur JSON. Un analyseur avance tant que ce qu’il lit peut suivre ce qui précède, donc une virgule manquante en fin de ligne 12 est signalée au début de la ligne 13, là où la clé suivante apparaît et n’a pas le droit d’être là.

Regardez donc au-dessus. Le repère marque le premier caractère qui n’a pas pu être accepté ; ce qui est réellement fautif est en général la fin de la ligne précédente, ou la valeur précédente. Une accolade fermante manquante est le cas extrême : elle est signalée à la fin du fichier, aussi loin soit-elle.

Il n’existe aucune norme pour un message d’erreur d’analyse JSON. Chrome et Node disent « at position 42 » et, dans les versions récentes, ajoutent une ligne et une colonne. Firefox donne une ligne et une colonne et pas de position. Safari ne donne parfois ni l’une ni l’autre.

Cette page prend le décalage en caractères quand il est disponible et calcule elle-même la ligne et la colonne, pour que la réponse soit la même dans tous les navigateurs plutôt que celle que le moteur local aura formulée. Quand un message ne porte ni l’un ni l’autre, elle le dit au lieu de deviner : un mauvais numéro de ligne dans un long fichier coûte plus de temps qu’aucun numéro du tout.

Cela signifie que le document est syntaxiquement du JSON : les accolades s’équilibrent, les chaînes sont correctement délimitées et échappées, les nombres sont des nombres. C’est ce que vérifie un analyseur, et c’est ce qui échoue quand quelque chose refuse votre fichier avec une erreur peu explicite.

Cela ne signifie pas que le document a la bonne forme. Savoir s’il porte les champs qu’une API attend, si une valeur est dans les bornes, si une date en est une : c’est de la validation par schéma, et il faut un schéma pour cela. Si votre JSON s’analyse ici et reste refusé, le problème est passé de la syntaxe à la sémantique.

Une virgule finale avant une accolade ou un crochet fermant — légale en JavaScript, légale en JSON5, pas en JSON, et la raison pour laquelle la plupart des gens arrivent ici. Une apostrophe droite là où JSON exige un guillemet double. Un guillemet ou une barre oblique inverse non échappé à l’intérieur d’une chaîne, ce qui vient presque toujours d’un chemin Windows collé tel quel. Et un commentaire, que JSON n’a pas du tout.

La cinquième, plus rare et plus difficile à voir, est un caractère de contrôle non échappé dans une chaîne : un retour à la ligne ou une tabulation collés au lieu d’être écrits sous forme d’échappement. Invisible dans la plupart des éditeurs, et à soupçonner dès que le repère désigne quelque chose qui paraît parfaitement normal.

Le type de plus haut niveau, le nombre de clés comptées sur tout le document, la profondeur d’imbrication et la taille en octets. Ils sont là parce que « valide » tout seul est un oui sans contenu, et parce que chacun des quatre répond à une question que quelqu’un se pose réellement.

La profondeur est celle qu’il faut surveiller. Au-delà de six niveaux environ, on a en général un modèle de données qui a poussé plutôt qu’un modèle conçu, et c’est un bon prédicteur du fait que le code qui consommera le document sera pénible à écrire. Les clés comptées par occurrence plutôt que par nom distinct répondent à une autre question : combien il y a là-dedans, et non combien de noms de champs existent.

Un `é` dans une chaîne JSON est parfaitement légal, sans échappement d’aucune sorte : la spécification exige de l’UTF-8, et un accent n’est qu’un caractère de plus. Une erreur d’analyse sur un document français ne vient donc jamais de l’accent lui-même.

Elle vient de ce qui est arrivé aux octets avant. Un fichier tronqué au milieu d’une séquence UTF-8, un export passé par une couche Latin-1, un copier-coller depuis un terminal mal configuré : dans les trois cas les octets ne forment plus de caractères valides, et l’analyseur s’arrête sur la chaîne qui les contient. Le repère désigne alors un mot qui semble normal à l’écran, ce qui est le signe le plus fiable de ce genre de dégât.

Les journaux au format NDJSON contiennent un document par ligne, sans virgule ni crochet autour : coller le fichier entier échoue au deuxième document, à la fin de la première ligne. Collez une seule ligne. Un fichier `.jsonl` a le même comportement, et pour la même raison.

Une réponse d’API copiée depuis un outil de développement arrive parfois entourée de guillemets, parce que ce qui a été copié est une chaîne contenant du JSON et non le JSON lui-même. Le repère se pose alors sur le tout premier caractère, ce qui est le diagnostic : retirez les guillemets extérieurs et défaites les échappements avant de recommencer.

Réparer un JSON demande de deviner l’intention. Une virgule finale se retire sans risque, mais un guillemet manquant peut se refermer à trois endroits différents, chacun donnant un document valide et une donnée différente. Un outil qui choisit à votre place vous rend un fichier qui s’analyse et qui n’est pas le vôtre.

Le refus est donc la fonctionnalité. Cette page vous donne l’endroit exact et vous laissez la décision à la personne qui sait ce que le document était censé dire — c’est-à-dire vous. C’est aussi pourquoi elle affiche la ligne fautive plutôt qu’une suggestion : la ligne est un fait, la suggestion serait une hypothèse.