Outils de développement · JSON formateur et validateur
Pourquoi JSON n'a aucun commentaire : la décision de conception et ses solutions de contournement
· Contexte
json normes validation
Les commentaires ont été délibérément supprimés de JSON. Cet article explique le raisonnement, pourquoi chaque tentative de les rajouter a créé un nouveau format et quelles sont vos options lorsqu'un fichier de configuration a vraiment besoin d'une note.
Le commentaire qui a interrompu la construction
Le commentaire qui a interrompu la construction : une note utile ajoutée à une configuration JSON et un analyseur qui s'est arrêté à la première barre oblique. L'auteur peut avoir copié un modèle à partir de JavaScript ou d'un éditeur compatible JSONC, tandis que l'outil de déploiement utilise le strict JSON. La mise en évidence de la syntaxe peut donner à la note un aspect légitime même si le consommateur rejette le premier marqueur de commentaire.
Les commentaires sont rejetés car la barre oblique n'est pas un jeton JSON où l'analyseur attend une valeur ou un membre. ToolAcre ne supprime pas silencieusement la syntaxe JSONC ou JSON5. Une propriété conventionnelle sous forme de commentaire est une donnée ordinaire et peut violer un schéma d'application même si la syntaxe stricte JSON l'accepte. Les affirmations historiques non étayées concernant la conception de JSON sont omises ou corrigées plutôt que présentées comme des faits établis sans preuves primaires ni source de normes traçables disponibles pour vérification.
Raison pour laquelle Crockford a supprimé les commentaires
Raison pour laquelle Crockford a supprimé les commentaires — une explication ultérieure indique que les commentaires avaient été utilisés pour transporter des directives d'analyse, compromettant l'interopérabilité entre les implémentations. La conséquence de conception pertinente est que la norme JSON n'a pas de jeton de commentaire. Les affirmations sur les motivations privées, la chronologie exacte ou la réponse universelle de l’industrie nécessitent des sources historiques non fournies par ce référentiel.
En conséquence, les affirmations historiques non étayées sont omises ou corrigées ici. La norme observable et le comportement de l'analyseur sont suffisants : le strict JSON échange des données via six types de valeurs et deux conteneurs, sans canal d'annotation. Cette contrainte empêche un destinataire d'attribuer une signification opérationnelle au texte qu'un autre destinataire ignore, mais elle rend également JSON moins confortable pour une configuration manuelle.
Ce qu'un validateur rapporte sur un commentaire
Ce qu'un validateur rapporte sur un commentaire — `//` et `/* */` ne sont pas dans la grammaire, donc l'erreur atterrit sur la première barre oblique avec une ligne et une colonne. Le scanner ne s'oppose pas aux mots contenus dans la note. Il ne peut pas commencer une valeur JSON, un nom de membre ou un séparateur valide par `/` à cette position.
Pour `{"port":8080, // local uniquement "secure":false}`, la virgule est valide et le prochain jeton légal doit être un nom de propriété entre guillemets ou une accolade fermante. La barre oblique viole cette attente. Supprimer uniquement la note laisse un séparateur valide et un membre suivant ; la suppression de la ponctuation à proximité peut créer une deuxième erreur. Revalidez la sortie stricte exacte après chaque modification.
Les formats qui ont ajouté des commentaires
Les formats qui ont ajouté des commentaires - JSONC autorise les commentaires autour de la syntaxe JSON par ailleurs familière, tandis que JSON5 ajoute des commodités telles que des clés d'identification sans guillemets et des virgules de fin. Hjson met l'accent sur l'édition humaine avec une syntaxe supplémentaire détendue. YAML a sa propre grammaire, y compris des commentaires, et n'est pas simplement JSON avec des annotations ajoutées.
L'acceptation est spécifique au consommateur : les paramètres de l'éditeur et la configuration TypeScript peuvent utiliser des analyseurs tolérants aux commentaires, tandis qu'un manifeste de package ou un corps d'API peut nécessiter un JSON strict. Kubernetes consomme généralement YAML ou JSON en fonction de ses outils. Nommer le format réel dans la documentation et la gestion des fichiers ; supprimer les extensions ou appeler chaque notation d'objet « JSON » masque les limites de compatibilité.
Solutions de contournement à l'intérieur du strict JSON
Solutions de contournement à l'intérieur du strict JSON — une clé conventionnelle `_comment` ou `//` stocke l'explication en tant que membre de chaîne ordinaire. Il survit à une analyse stricte car la clé et la valeur utilisent des jetons standard. Plusieurs notes nécessitent des clés uniques ou un tableau, car les noms de membres en double ne sont pas fiables et peuvent être réduits par les analyseurs.
La solution de contournement modifie le modèle de données. Un schéma avec `additionalProperties: false` peut rejeter l'annotation et une application peut la conserver ou la transmettre en tant que configuration réelle. Une documentation externe, un README voisin ou un schéma `description` fournit souvent un canal d'explication plus sûr. Utilisez des membres sous forme de commentaires uniquement lorsque chaque consommateur les autorise et les ignore explicitement.
Exemple concret : un fichier de paramètres annoté
Exemple pratique : un fichier de paramètres annoté – commencez par une source JSONC contenant `// seconds before retry` au-dessus de `"timeout":30`. Si la destination n'accepte que JSON, utilisez un analyseur qui comprend JSONC pour produire des données, puis sérialisez ces données en tant que JSON strict. L'artefact déployé devient `{"timeout":30}` tandis que la source maintenue conserve son explication.
Ne supprimez pas les commentaires contenant une expression régulière. Les séquences de barres obliques peuvent apparaître légitimement à l'intérieur de chaînes telles que des URL, et les modèles de commentaires en bloc peuvent s'étendre sur des lignes de manière à provoquer des erreurs de remplacement textuel. Gardez la source et l'artefact généré distincts, validez le résultat strict et organisez la régénération dans la construction. Cela préserve les notes de l'auteur sans prétendre que l'analyseur récepteur les prend en charge.
Ce que cela ne couvre pas
Ce que cela ne couvre pas : comment configurer des analyseurs individuels pour accepter les commentaires, ce qui est spécifique à l'outil et change souvent. Une option permissive dans une bibliothèque ne modifie pas la grammaire JSON et ne garantit pas qu'un autre service acceptera le même texte. Vérifiez l'analyseur, la version et la destination plutôt que de vous fier à l'affichage d'un éditeur.
Cet article évite également les affirmations non fondées sur le moment précis où les commentaires ont été supprimés, qui a adopté chaque solution de contournement en premier ou si une décision de conception à elle seule a causé la popularité de JSON. De telles affirmations historiques nécessitent des sources primaires indépendantes. Ici, ils sont omis ou corrigés ; la conclusion soutenue se limite à la syntaxe stricte actuelle, au comportement du référentiel et aux différences opérationnelles entre les formats nommés.
À retenir : JSON est un format d'échange de données, pas un langage de configuration
À retenir : JSON est un format d'échange de données, pas un langage de configuration riche en commentaires - et le validateur montre exactement où une note enfreint la grammaire stricte. Lorsque les humains ont besoin d'annotations, choisissez un format que l'outil consommateur prend officiellement en charge ou conservez une source annotée qui génère un artefact strict distinct. Ne présumez pas que les commentaires seront ignorés de manière inoffensive.
Si un JSON strict est obligatoire, déplacez l'explication vers la documentation ou utilisez des métadonnées approuvées par le schéma, puis validez le document final. ToolAcre signale intentionnellement la première barre oblique au lieu de supprimer silencieusement du matériel, car une conversion silencieuse pourrait modifier les chaînes ou masquer une incompatibilité de format. Le contexte historique doit rester tout aussi discipliné : les affirmations non étayées sont omises ou corrigées, tandis que la syntaxe observable et le comportement de l'analyseur portent la conclusion.