je construis Toolz.dev[TRADUCTION], et avant cela, j'ai passé des années à expédier des plugins WordPress et des API Laravel Dans tout cela, le seul message d'erreur sur lequel j'ai perdu le plus d'heures est une variante de " ; jeton inattendu dans JSON à la position 428." ; il ne vous dit presque rien Il n'y a pas de ligne, pas de colonne, et la position qu'il nomme est fréquemment quelques caractères au-delà de ce qui ne va pas Vous finissez par compter les caractères dans un blob minifié à la main, ou coller toute la charge utile dans un éditeur et plisser les yeux J'ai construit le Validateur JSON je n’ai donc plus jamais besoin de recommencer, et c’est le guide de ce qu’il fait et pourquoi valider JSON est plus délicat qu’il n’y paraît.
tl;dr : Un validateur JSON vérifie le texte par rapport à la grammaire dans la RFC 8259 et, lorsque le texte est cassé, vous indique la ligne, la colonne et le caractère exacts de la première erreur, formulés en fonction de ce à quoi il s'attend. Il capture également les choses qu'un analyseur normal cache : les clés en double, qui sont silencieusement réduites à la dernière valeur, et il rapporte la structure d'un document valide (nombre d'objets, de tableaux et de clés, profondeur d'imbrication et taille d'octet). Ce n'est pas un formateur. Un formateur suppose que l'entrée est déjà valide ; un validateur est la chose que vous atteignez précisément lorsqu'il ne l'est pas.
Qu'est-ce que cela signifie pour JSON d'être valide ?
JSON est un petit format avec une grammaire stricte La norme actuelle est RFC 8259, qui s'aligne avec ECMA-404[TRADUCTION], et entre eux, ils définissent exactement ce que peut contenir un document valide Un texte JSON est une valeur unique Cette valeur est un objet, un tableau, une chaîne, un nombre, true, false, ou null. Les objets sont enveloppés dans des appareils orthodontiques et tiennent séparés par des virgules "key": value paires. Les tableaux sont enveloppés entre parenthèses et contiennent des valeurs séparées par des virgules. Les chaînes sont enveloppées dans des guillemets doubles, jamais de guillemets simples. Les nombres suivent une forme spécifique sans zéros non significatifs ni point décimal final. Il n'y a pas de commentaires et il n'y a pas de virgules traînantes.
Cette dernière phrase est l'endroit où la plupart des JSON du monde réel se trompent, car beaucoup de gens JSON écrivent à la main n'est pas vraiment JSON C'est un fichier de configuration avec // commentaires, ou un objet copié à partir d'une source JavaScript où les guillemets simples et les virgules de fin conviennent, ou un luminaire édité à la main dans lequel quelqu'un a ajouté un champ et laissé une virgule pendante. Tous ces éléments sont rejetés par un analyseur strict et un validateur' ; Le travail consiste à les rejeter à un endroit spécifique plutôt qu'avec un haussement d'épaules.
Un point qui mérite d'être éclairci, car il fait trébucher les personnes qui ont appris le JSON il y a des années : une valeur nue est un document JSON complet et valide. 42 à lui seul est valable JSON Ainsi est "hello"[TRADUCTION], et il en est de même true. Le vieux RFC4627 requis le niveau supérieur pour être un objet ou un tableau, mais cette restriction a été abandonnée en 2014 lorsque la RFC 7159 (plus tard 8259) l'a remplacé Si un outil vous le dit 42 n'est pas valide JSON, cet outil suit une spécification obsolète depuis plus d'une décennie.
Pourquoi JSON.parse est-il un si mauvais rapporteur d'erreurs ?
La raison pour laquelle un validateur dédié gagne sa place est que l'analyseur intégré à votre langue est optimisé pour le chemin heureux, et non pour expliquer le chemin triste. JSON.parse dans un navigateur lance un SyntaxError dont le message est spécifique au moteur et vous donne généralement un décalage de caractère sans ligne ni colonne. V8 dit " ; jeton inattendu} dans JSON à la position 148." ; Firefox dit " ; JSON.parse : caractère inattendu à la ligne 1 colonne 149." ; Safari dit encore quelque chose de différent Aucun d'entre eux ne vous dit ce qu'ils attendaient, et la position est mesurée dès le début de la chaîne, ce qui est inutile au moment où votre JSON a plus de quelques lignes.
Le validateur sur Toolz.dev n'utilise pas JSON.parse. Il parcourt le texte lui-même avec un analyseur récursif-descente écrit à la main, en suivant la ligne et la colonne au fur et à mesure, de sorte que lorsqu'il s'arrête, il peut vous remettre les trois coordonnées : la ligne, la colonne et le décalage absolu des caractères Plus important encore, il connaît la règle de grammaire qu'il était au milieu de, donc le message est spécifique. Au lieu de " ; jeton inattendu, " ; vous obtenez " ; La virgule de déplacement n'est pas autorisée avant le corset de fermeture, " ; ou " ; La différence de fichier de traçage prévue ou de membre de fermeture est cinq secondes.
Il dessine également un caret sous le caractère exact sur la ligne incriminée, comme le fait un compilateur Lorsque vous regardez la ligne 34 d'un fichier de configuration, " ; colonne 12" ; est bien, mais a ^ s'asseoir directement sous la citation égarée est plus rapide.
Quelles erreurs JSON le validateur attrape-t-il par son nom ?
Ce sont les échecs que je vois le plus souvent, à la fois dans mon propre travail et dans les threads de support pour des outils comme celui-ci Le validateur nomme chacun plutôt que de signaler une erreur générique de jeton.
| Erreur | À quoi ça ressemble | Pourquoi il est invalide |
|---|---|---|
| Comma traînante | {"a": 1,} ou [1, 2,] |
JSON n'a pas de virgules de fin ; la grammaire standard' ; n'en autorise tout simplement pas avant un corset ou un support de fermeture |
| Citations uniques | {'name': 'Liton'} |
Les chaînes et les clés doivent utiliser des guillemets doubles ; les guillemets simples sont une habitude JavaScript, pas JSON |
| Comma manquante | {"a": 1 "b": 2} |
Chaque membre après le premier doit être précédé d'une virgule |
| observation | {"a": 1} // note |
JSON n'a pas de syntaxe de commentaire ; le // et tout ce qui suit est un contenu inattendu |
| Clé non citée | {name: "Liton"} |
Les clés sont des chaînes et doivent être citées, contrairement aux littéraux d'objets JavaScript |
| Zéro leader | {"n": 007} |
Un nombre peut ne pas avoir de zéro non significatif, donc 007 est invalide ; écrire 7 |
| Point décimal de traînage | {"n": 5.} |
La fraction après une virgule décimale nécessite au moins un chiffre |
| Caractère de contrôle brut | un onglet littéral ou une nouvelle ligne à l'intérieur d'une chaîne | Les caractères de contrôle à l'intérieur des chaînes doivent être échappés \t, \n, et ainsi de suite |
| NaN ou Infinity | {"n": NaN} |
Ceux-ci sont valides en JavaScript mais ne sont pas des valeurs JSON |
| Chaîne non terminée | {"a": "oops} |
Une chaîne sans guillemet de fermeture s'exécute jusqu'à la fin de l'entrée |
Chacun d'entre eux produit un message en langage clair et une position. Le cas leader-zéro est un bel exemple de la raison pour laquelle un analyseur spécialement conçu aide : un analyseur générique lit 007 comme le nombre 0 et puis des voyages sur le 7 comme " ; contenu supplémentaire, " ; vous pointant vers le 7[TRADUCTION], lorsque le vrai problème est les deux zéros devant lui Le validateur vérifie d'abord le modèle menant-zéro et vous le dit directement.
Qu'en est-il des clés en double ?
Voici celui qui m'a mordu en production plus que n'importe quelle erreur de syntaxe, car ce n'est pas du tout une erreur de syntaxe C'est valable JSON :
{
"timeout": 30,
"retries": 3,
"timeout": 60
}
La RFC 8259 indique que les noms dans un objet " ; DEVRAIT être unique, " ; mais il n'interdit pas les doublons, un analyseur est donc tenu d'accepter cela. Ce qui se passe ensuite, c'est là que commence le problème : la norme dit que le comportement avec des noms en double est imprévisible, et en pratique, presque tous les analystes conservent la dernière valeur et rejettent silencieusement les précédentes. Cet objet analyse donc {"timeout": 60, "retries": 3}, et le "timeout": 30 vous avez soigneusement défini en haut du fichier est parti sans avertissement Si deux personnes ont modifié la configuration, ou une fusion s'est mal passée, ou une étape de templating a émis la même clé deux fois, vous avez un bug qu'aucun analyseur ne signalera jamais pour vous.
Le validateur l'affiche La détection de double clé est activée par défaut, et comme un double est légal, il est signalé comme un avertissement plutôt que comme une erreur : le document est toujours valide, mais on vous dit chaque clé qui apparaît plus d'une fois dans le même objet, avec sa ligne et un Pointeur JSON chemin pour que vous puissiez le trouver à l'intérieur d'une structure imbriquée Si vous voulez vraiment des doublons, vous pouvez désactiver le chèque La plupart du temps, voir l'avertissement est le moment où vous réalisez ce qui n'a pas fonctionné.
En quoi un validateur est-il différent d'un formateur ?
Les gens utilisent les mots de manière interchangeable, et les outils se chevauchent, mais ils répondent à des questions différentes. Un Formateur JSON prend JSON que vous croyez déjà valide et le réimprime avec une indentation cohérente afin qu'un humain puisse le lire Si vous remettez un JSON cassé au formateur, le mieux qu'il puisse faire est de refuser. Un validateur' ; tout le but est le cas cassé : il vous indique où et pourquoi. Le validateur Toolz.dev effectue les deux tâches, car une fois qu'il a confirmé qu'un document est valide, il l'a déjà analysé, il imprime donc le résultat dans le même passage. Mais la fonctionnalité phare est le diagnostic, pas l'indentation.
La même relation s'applique aux outils voisins. Le Minificateur JSON supprime les espaces pour réduire une charge utile, ce qui n'a de sens que sur une entrée valide. Le Trieur JSON réorganise les clés pour les diff stables, toujours sur une entrée valide. Le JSON s'échappe et ne s'échappe pas l'outil traite de l'intégration de JSON dans une chaîne. Et le Testeur JSONPath interroge un document que vous avez déjà confirmé est bien formé La validation est l'étape qui les précède tous, c'est pourquoi c'est celui que j'exécute en premier chaque fois qu'une réponse API ou un fichier de configuration se comporte étrangement Il y a un tour plus large de la façon dont ceux-ci s'emboîtent dans le Guide ultime des outils JSON.
Que vous disent les statistiques de structure ?
Lorsqu'un document valide, l'outil rapporte sa forme : combien d'objets et de tableaux il contient, combien de clés, combien de chaînes, de chiffres, de booléens et de nuls, à quelle profondeur il niche et sa taille dans les deux caractères et les octets UTF-8. Ce n'est pas de la décoration. Lorsqu'on vous transmet une réponse API inconnue, le numéro de profondeur vous indique en un coup d'œil si vous avez affaire à un enregistrement plat ou à un arbre profondément imbriqué, et le nombre de clés vous indique à peu près combien de travail l'analyse sera effectuée.
Le chiffre des octets compte plus que ce à quoi les gens s'attendent Les limites de taille de demande, les limites de file d'attente de messages et les limites de colonne de base de données sont presque toujours mesurées en octets, pas en caractères, et les deux diffèrent au moment où votre JSON contient quelque chose en dehors de l'ASCII. Un emoji ou un nom accentué est un caractère à l'écran mais deux, trois ou quatre octets sur le fil Si une charge utile se heurte à une limite de 256 Ko, le nombre de caractères vous induira en erreur et le nombre d'octets ne le fera pas. Le validateur calcule la véritable longueur des octets UTF-8 afin que le nombre que vous voyez soit le nombre que la limite compte.
Comment je l'utilise
Mon workflow est ennuyeux et rapide, ce qui est le point Quand une intégration se rompt, je copie le corps de réponse brut tout droit sorti de l'onglet réseau et je le colle dans le validateur Si c'est valide, le résultat vert et les statistiques me disent que le problème est ailleurs, dans mon code plutôt que leurs données, et j'ai exclu toute une classe de causes en deux secondes Si c'est invalide, je reçois la ligne et la colonne, je le corrige et je passe à autre chose Quand je suis en train d'éditer un fichier de configuration à la main, je le colle avant de m'engager, la plupart du temps pour attraper la virgule arrière que je semble toujours laisser derrière moi et la clé occasionnelle dupliquée d'un copier du tas. Pour quiconque assemble son propre kit, l'essential est l'essentiel Boîte à outils pour les développeurs Web.
L'angle de confidentialité n'est pas non plus une réflexion après coup Les personnes JSON qu'il faut le plus valider sont exactement le JSON avec lequel elles doivent être les plus prudentes : réponses API transportant des jetons, fichiers de configuration avec des informations d'identification, charges utiles avec des données clients Tout ce que le validateur fait se passe dans votre navigateur, en JavaScript, sur votre machine Rien n'est téléchargé, enregistré ou stocké Vous pouvez le prouver en ouvrant l'onglet réseau pendant que vous validez, ou en vous déconnectant d'internet et en regardant l'outil continuer à fonctionner.
Questions fréquentes
Pourquoi mon JSON dit-il qu'il n'est pas valide alors qu'il a l'air bien ?
Les raisons les plus courantes sont une virgule de fin avant un corset ou un crochet de fermeture, des guillemets simples où JSON nécessite des guillemets doubles, une virgule manquante entre deux membres ou un commentaire, ce que JSON ne permet pas du tout. Les quatre sont faciles à manquer à l'œil nu, en particulier dans un grand fichier. Le validateur nomme celui qu'il a trouvé et vous donne la ligne et la colonne exactes, donc au lieu de scanner l'ensemble du document, vous accédez directement au caractère sur lequel il s'est arrêté.
Un seul numéro ou une chaîne est-il valide JSON seul ?
Oui. Selon la RFC 8259, toute valeur JSON est un texte JSON complet, donc 42, "hello", true, et null tous valident par eux-mêmes La règle selon laquelle le niveau supérieur devait être un objet ou un tableau est venue de l'ancienne RFC 4627 et a été supprimée en 2014 Un outil qui rejette une valeur nue suit une spécification obsolète.
Le validateur modifie-t-il ou télécharge-t-il mes données ?
Non. Il analyse le texte dans votre navigateur et ne l'envoie jamais nulle part. Sur un document valide, il produit une copie joliment imprimée pour plus de commodité, mais cette copie est générée localement et l'original n'est jamais transmis, enregistré ou stocké. Comme il n'y a pas d'aller-retour sur le serveur, l'outil fonctionne également avec le réseau déconnecté une fois la page chargée.
Pourquoi devrais-je me soucier des clés en double si le JSON est toujours valide ?
Parce qu'un duplicata signifie presque toujours une perte de données que vous n'aviez pas l'intention La norme autorise les clés en double mais laisse leur gestion indéfinie, et en pratique les analyseurs ne conservent que la dernière valeur et abandonnent le reste Donc une configuration où timeout apparaît deux fois et perd tranquillement le premier paramètre Le validateur vous avertit de chaque touche répétée avec sa position, qui est généralement le moment où vous repérez une mauvaise fusion ou une erreur de copier-coller.
Est-ce que cela peut valider JSON avec des commentaires, comme un fichier de paramètres tsconfig ou VS Code ?
Non, et c'est délibéré Ces fichiers sont JSON with Comments (JSONC) ou JSON5, qui sont des formats distincts qui assouplissent les règles Le validateur cible la RFC 8259 stricte, il signalera donc un commentaire comme une erreur Si vous avez besoin de commentaires dans un fichier de configuration, c'est un signal le format devrait être quelque chose construit pour lui, tel que YAML ou TOML, plutôt que JSON étendu au-delà de ce que la norme permet.
Quelle est la différence entre valider et formater JSON ?
La validation vérifie si le texte obéit à la grammaire JSON et, si ce n'est pas le cas, vous indique exactement où il se brise Le formatage suppose que le texte est déjà valide et ajuste seulement son espace pour la lisibilité Vous prenez contact avec un validateur lorsque quelque chose ne va pas et que vous devez savoir quoi ; vous prenez contact pour un formateur lorsque tout va bien et que vous voulez juste qu'il soit lisible Cet outil fait les deux, mais sa raison d'être est le diagnostic.
Quelle taille de fichier puis-je valider ?
Confortablement dans les dizaines de mégaoctets, limité seulement par votre navigateur' ; s mémoire, car le document entier est analysé en un passage sur votre appareil Il n'y a pas de plafond de taille de téléchargement car il n'y a pas de téléchargement Pour un fichier véritablement énorme, dans les gigaoctets, un validateur de ligne de commande de streaming est le meilleur instrument, puisque le navigateur tient tout le texte en mémoire à la fois.
