Outils de développement · JSON formateur et validateur
Pourquoi un fichier de lignes JSON échoue à la validation à la ligne 2, colonne 1
· Comment ça marche
json flux de travail du développeur validation
Un fichier .jsonl est constitué de plusieurs documents JSON, pas un, donc un validateur strict s'arrête exactement là où commence le second. Cet article explique les lignes JSON et les conventions NDJSON et comment les valider un enregistrement à la fois.
Valable sur chaque ligne, invalide en tant que fichier
Valable sur chaque ligne, invalide en tant que fichier - l'exportation que chaque outil en aval lit avec plaisir mais qu'un validateur rejette à la deuxième ligne. Un expéditeur de journaux peut consommer chaque nouvelle ligne comme limite d'enregistrement, mais un analyseur strict JSON considère l'intégralité du fichier comme une seule entrée. Le premier objet est complet JSON ; l'accolade ouvrante suivante est une deuxième valeur racine illégale.
ToolAcre valide un texte JSON, et non des lignes JSON. Une fois que l'analyseur a terminé la première valeur racine, tout caractère autre qu'un espace est signalé comme inattendu après la fin de la valeur JSON. Il n'offre pas de validation ou de conversion NDJSON par ligne comme solution de secours cachée. Cette distinction empêche qu'un résultat vert implique que chaque enregistrement d'un flux orienté ligne a été vérifié.
Un texte, une valeur — ce que la RFC 8259 définit comme un texte JSON et pourquoi deux valeurs de niveau supérieur consécutives sont une erreur de grammaire
Un texte, une valeur — ce que la RFC 8259 définit comme un texte JSON et pourquoi deux valeurs de niveau supérieur consécutives sont une erreur de grammaire. Un texte JSON est une valeur sérialisée, donc un objet, un tableau, une chaîne, un nombre, un booléen ou une valeur nulle peut se trouver à la racine. Des espaces peuvent entourer cette valeur, mais ils ne peuvent pas séparer plusieurs racines en un document valide plus grand.
Par exemple, `{"ok":true} {"ok":false}` contient deux objets individuellement valides mais n'est pas un seul texte JSON. L'analyse du premier objet consomme une valeur complète ; l'analyse de la chaîne entière doit alors rejeter le deuxième `{`. Pour représenter les deux valeurs dans JSON ordinaire, placez-les dans un tableau et ajoutez la virgule requise entre les éléments du tableau.
JSON Lignes et NDJSON
Lignes JSON et NDJSON — les conventions délimitées par des nouvelles lignes, pourquoi elles existent pour le streaming et les journaux, et en quoi elles diffèrent d'un tableau JSON. Chaque ligne physique porte une valeur JSON complète, normalement un objet, et la nouvelle ligne agit comme un cadrage en dehors de la grammaire JSON. Les producteurs peuvent ajouter des enregistrements et les consommateurs peuvent les traiter progressivement sans charger une collection complète.
Un tableau a à la place un crochet ouvrant, des éléments séparés par des virgules et un crochet fermant, ce qui fait de l'ensemble du fichier une seule valeur JSON. C'est pratique pour les API qui renvoient une collection limitée, mais gênant pour un flux d'événements à croissance indéfinie. Un fichier JSON Lines tronqué peut conserver tous les enregistrements antérieurs complets ; un tableau tronqué laisse généralement la valeur englobante inachevée.
Pourquoi l'erreur se trouve toujours à la ligne 2, colonne 1
Pourquoi l'erreur se trouve toujours à la ligne 2, colonne 1 — l'analyseur termine la première valeur, attend la fin de la saisie et rencontre le premier caractère du deuxième enregistrement. La nouvelle ligne elle-même est un espace de fin légal, elle ne déclenche donc pas l'échec. L’accolade ouvrante de l’enregistrement suivant est le premier jeton qui contredit l’état du document terminé.
Cet emplacement est une preuve de diagnostic plutôt qu'une affirmation selon laquelle le deuxième objet est mal formé. Si le rapport pointe systématiquement vers le premier caractère autre qu'un espace après une racine valide, inspectez la forme du fichier avant de modifier la ponctuation. La suppression de l'accolade corrompt l'enregistrement ; le choix d'un lecteur sensible aux lignes ou la conversion des enregistrements en un tableau résout l'inadéquation réelle du cadrage.
Exemple pratique : validation de trois enregistrements de journal
Exemple pratique : validation de trois enregistrements de journal – vérification de chaque ligne individuellement plutôt que de les envelopper dans un tableau avec des virgules. Supposons que les lignes contiennent `{"level":"info"}`, `{"level":"warn"}` et `{"level":"error"}`. Un validateur orienté ligne analyse trois entrées distinctes et peut identifier l'enregistrement exact s'il manque un guillemet ou une virgule finale.
Pour une vérification stricte de l'ensemble du document, transformez l'échantillon en `[{"level":"info"},{"level":"warn"},{"level":"error"}]`. Les parenthèses établissent une racine et les virgules délimitent ses éléments. Ne remplacez pas simplement les nouvelles lignes par des virgules : cela produit trois racines séparées par des signes de ponctuation à moins que le tableau environnant ne soit ajouté, et cela peut mal gérer les lignes vides que la convention source peut interdire ou ignorer.
Conversion entre les deux formes
Conversion entre les deux formes — lorsqu'un tableau d'habillage est approprié et lorsqu'il irait à l'encontre du point de sortie délimité par des lignes. Un export fini destiné à une requête API, un éditeur ou un validateur strict peut souvent devenir un tableau. La conversion doit d'abord analyser chaque enregistrement, car la concaténation textuelle ne peut pas prendre en compte en toute sécurité les caractères d'échappement incorporés ou les lignes invalides.
Conservez les lignes JSON lorsque des enregistrements arrivent en continu, que des fichiers sont ajoutés ou que les consommateurs ont besoin d'une mémoire limitée et d'une récupération au niveau de l'enregistrement. La conversion d'un flux d'événements de plusieurs gigaoctets en un seul tableau nécessite de conserver l'état du conteneur et retarde une analyse complète jusqu'à l'arrivée du crochet fermant. Dans l'autre sens, sérialisez chaque élément du tableau de manière compacte sur une ligne et définissez si les lignes vides ou les nouvelles lignes finales sont autorisées.
Ce que cela ne couvre pas
Ce que cela ne couvre pas : JSON concaténé sans nouvelles lignes ni cadrage de séparateur d'enregistrement (RFC 7464), qui nécessitent des analyseurs dédiés. Les valeurs placées directement ensemble ne peuvent pas être divisées en toute sécurité avec une simple opération de ligne, en particulier lorsque les racines peuvent être des nombres ou des chaînes. La RFC 7464 utilise un caractère séparateur d'enregistrement ASCII pour encadrer les séquences de texte JSON plutôt que de s'appuyer uniquement sur des nouvelles lignes visibles.
Il ne valide pas non plus les règles d'application partagées par les enregistrements. L'analyse de chaque ligne ne peut pas prouver que les horodatages sont ordonnés, que les identifiants sont uniques ou que tous les objets utilisent le même schéma. Ces vérifications appartiennent après le cadrage des enregistrements et l’analyse syntaxique. De même, une nouvelle ligne intégrée comme séquence d'échappement ` ` à l'intérieur d'une chaîne se trouvent des données, pas une limite physique, et un lecteur de ligne conforme doit préserver cette distinction.
À retenir : sachez quelle forme vous tenez
À retenir : sachez quelle forme vous tenez et comment la position du validateur vous indique instantanément qu'un fichier est délimité par des lignes. Un échec au premier jeton de la ligne deux après une valeur complète de la première ligne indique fortement plusieurs enregistrements encadrés, et non une syntaxe cassée dans le premier enregistrement. Vérifiez l'extension, la documentation du producteur et le consommateur attendu avant de modifier les données.
Utilisez un analyseur JSON Lines ou NDJSON pour valider les enregistrements indépendamment lorsque la nouvelle ligne est intentionnelle. Utilisez un tableau lorsque la destination nécessite une collection JSON complète. ToolAcre rejette correctement le fichier multi-racine car son contrat est une validation stricte en texte unique ; le rejet protège ce contrat plutôt que de montrer que JSON délimité par une nouvelle ligne est intrinsèquement défectueux. Faites correspondre le validateur au format de cadrage.