Outils de développement · JSON formateur et validateur
Valide JSON vs valide par rapport à un schéma : deux significations de "valide"
· Contexte
json normes validation
Un validateur disant que votre JSON est valide signifie seulement qu'il analyse. Cet article explique les niveaux de validité (syntaxe, structure, sémantique) et pourquoi le schéma JSON existe pour tout au-delà de la grammaire.
Valide et toujours rejeté
Une requête peut être impeccable JSON et rester inacceptable pour une API. `{"username":"nori","plan":"gold"}` a des délimiteurs équilibrés, des noms cités et des valeurs légales, mais un service peut exiger un e-mail, rejeter le nom du plan ou interdire la création de compte dans l'état actuel. L'analyseur et l'application répondent à des questions différentes, les deux résultats peuvent donc être corrects.
ToolAcre répond uniquement à la première question : ce texte peut-il être analysé comme JSON strict dans ses limites de saisie ? Il ne charge pas de schéma, ne vérifie pas les propriétés requises, ne vérifie pas les formats, ne contacte pas une base de données et n'évalue pas les règles métier. Lorsque l'outil indique Valide, lisez cela comme une « syntaxe JSON bien formée », et non comme une approbation du système qui consommera la valeur.
Niveau un : syntaxe bien formée
La validation syntaxique vérifie la grammaire JSON : une valeur de niveau supérieur, des conteneurs correctement appariés, des noms d'objets cités, des virgules et deux-points valides, des chaînes légales, des nombres légaux et des littéraux exacts. Il rejette `NaN` et `Infinity`, les commentaires, les virgules finales et les chaînes entre guillemets simples. Il accepte toute forme grammaticale valide, y compris un nombre isolé ou un objet avec des champs inconnus.
La source mal formée présente un point d'échec textuel, donc ToolAcre peut signaler une ligne et une colonne pour le premier caractère impossible. Une virgule manquante peut entraîner le report de la citation suivante ; une virgule finale peut entraîner le signalement du délimiteur fermant. La correction de la syntaxe crée une valeur analysable mais n'établit pas que la valeur a la forme ou la signification attendue par un autre programme.
Niveau deux : la forme
La validation de forme demande si la valeur analysée correspond à un contrat déclaré. Un schéma utilisateur peut exiger `email`, contraindre `age` à un entier d'au moins 18, limiter `tier` à `free` ou `pro` et interdire les propriétés inconnues. `{"email":false,"tier":"gold"}` est une syntaxe JSON valide mais échoue à ces règles structurelles car les types de valeur et les choix autorisés sont erronés.
JSON Le schéma est un moyen d'exprimer de telles contraintes, mais ToolAcre ne l'exécute pas. Un validateur de schéma signale généralement un chemin d'instance tel que `/tier`, un mot-clé tel que `enum` et un message explicatif plutôt qu'un curseur d'analyseur. Conservez la version du schéma et le contrat de l'API à côté de la charge utile lors du diagnostic de ce niveau ; changer la ponctuation ne réparera pas une valeur correctement analysée de la mauvaise forme.
Niveau trois : signification
La signification dépend de faits et de règles au-delà de la forme statique du document. Un `accountId` peut avoir le modèle de chaîne correct tout en ne nommant aucun compte. Une date de début peut correspondre à un format de style ISO tout en tombant après la date de fin. Une quantité peut être positive mais dépasser le stock actuel. Ces échecs nécessitent le contexte de l'application, l'état stocké ou les relations entre les champs.
Certaines contraintes sémantiques peuvent être approximées dans un schéma, mais beaucoup appartiennent à la logique de service où les données faisant autorité et l'état de la transaction sont disponibles. Les réponses d'erreur à ce niveau doivent identifier le champ ou la règle concernée sans prétendre que le texte JSON était mal formé. ToolAcre ne peut pas reproduire ces décisions car il ne connaît pas le contrat et n'envoie pas l'entrée à l'application propriétaire de la règle métier.
Exemple concret : une charge utile via trois contrôles
Commencez par `{"sku":"A-19","quantity":3,"warehouse":"north"}`. ToolAcre l'accepte : tous les noms et valeurs suivent la grammaire JSON. Un schéma peut alors nécessiter un objet, une chaîne SKU non vide, une quantité entière positive et l'un des codes d'entrepôt documentés. Supposons que cette charge utile dépasse également ces contraintes. Aucun des deux contrôles n'a confirmé que le SKU A-19 existe ou que North détient trois unités.
Le service d'inventaire effectue la troisième vérification par rapport aux enregistrements actuels et peut rejeter la demande comme indisponible. La modification de l'indentation ne peut pas modifier ce résultat. Si `quantity` était écrit sous la forme `03`, la syntaxe échouerait en premier ; s'il s'agissait de `"3"`, l'analyse réussirait mais la vérification du type de schéma échouerait ; avec le numérique `3`, seule la règle du stock de bétail demeure. Un même champ peut donc échouer au niveau de trois couches distinctes pour trois raisons distinctes.
Où appartient chaque chèque
Exécutez la validation de la syntaxe le plus tôt possible lors de l'édition, car les vérifications ultérieures ne peuvent pas fonctionner de manière fiable sur du texte qui n'est pas analysé. Appliquez la forme déclarée à chaque limite d'application non fiable plutôt que de supposer qu'un client l'a déjà fait. Évaluez les invariants métier dans le composant qui possède l'état requis, en particulier lorsque la réponse peut changer entre les requêtes.
Les vérifications côté client améliorent les commentaires mais ne remplacent pas l'application côté serveur. À l’inverse, une réponse du serveur indiquant « JSON invalide » doit être réservée aux échecs d’analyse plutôt que utilisée pour chaque demande rejetée. Une séparation claire produit des diagnostics utiles : ligne et colonne pour la syntaxe, chemins d'instance pour les contraintes structurelles et codes ou messages spécifiques au domaine pour les conflits sémantiques. ToolAcre ne fournit que la première catégorie.
Ce que cela ne couvre pas
Ce formateur ne crée ni n'évalue le schéma JSON, ne sélectionne pas un brouillon de schéma, ne résout pas les références de schéma, n'insère pas de valeurs par défaut ou ne force pas les chaînes à entrer des nombres. Il ne connaît pas non plus le document OpenAPI d’une API ni les conventions de validation personnalisées. Fournir un schéma avec l'entrée ne changerait pas le résultat de ToolAcre car il n'y a aucune étape de traitement de schéma dans cet outil.
La validation de la syntaxe ne détecte pas non plus les noms d'objets en double ici ; `JSON.parse` conserve la dernière occurrence avant le formatage. Il ne garantit pas non plus la précision numérique, les octets canoniques, le rendu ou l'autorisation sécurisé. Chacune de ces préoccupations nécessite son propre contrat et sa propre mise en œuvre. Évitez de les regrouper dans un seul badge vert « valide », car cela masquerait les preuves recueillies et les questions qui n’ont jamais été posées.
À retenir : « valide » nécessite un qualificatif
Qualifiez chaque demande de validation. « Valide JSON » signifie que le texte suit la grammaire. « Valide par rapport à ce schéma » signifie que la valeur analysée satisfait à un contrat structurel nommé. « Accepté par le service » signifie que les règles d'application actuelles autorisent l'opération. Le passage d'une couche est nécessaire pour passer à la suivante dans de nombreux flux de travail, mais cela ne prouve jamais que toutes les couches ultérieures ont réussi.
Utilisez ToolAcre pour formater et vérifier une syntaxe stricte, y compris le rejet des littéraux non JSON tels que `NaN` et `Infinity`. Utilisez ensuite le schéma et l’application qui régissent réellement la charge utile. Lorsqu'une requête échoue toujours, lisez l'erreur sur sa propre couche au lieu de reformater à plusieurs reprises le bon JSON. L'outil n'a pas de vérification de schéma, et cette limite explicite est plus utile qu'une promesse trop large de validité.