JSON peut-il avoir des commentaires
L’essentiel : La RFC 8259 n'a aucune syntaxe de commentaire, donc // et les commentaires de bloc font lever JSON.parse. Utilisez plutôt JSON5 ou JSONC, un champ _comment, une description de Schema, ou YAML.
L'essentiel : ne mettez jamais de commentaires dans du JSON standard ; utilisez JSONC ou JSON5 pour la configuration locale que seuls des humains éditent, déplacez les explications dans un description de JSON Schema quand le fichier traverse des systèmes, et passez à YAML ou TOML dès que le volume d'annotation grandit.
Non.
Tout parseur conforme aux normes rejette ceci :
{
"port": 8080 // local development only
}
Chrome rapporte SyntaxError: Unexpected token }. Le parseur a heurté /, qui ne peut commencer aucune valeur JSON, et s'est arrêté.
Pourquoi la spécification omet volontairement les commentaires
La RFC 8259 définit six valeurs : objet, tableau, nombre, chaîne, true/false, null. Il n'y a aucune production de commentaire.
Les commentaires ont été proposés tôt et rejetés pour une raison concrète : une fois les commentaires légaux, quelqu'un les utilise pour porter des directives — inclusions conditionnelles, variables de gabarit — et chaque parseur développe son propre dialecte. L'interopérabilité casse au premier saut. JSON est délibérément uniquement des données, sans rien d'exécutable à l'intérieur.
Quatre façons de garder vos notes
1. Utilisez un surensemble. JSON5 et JSONC acceptent les deux styles de commentaire. Le settings.json et le tsconfig.json de VS Code sont du JSONC.
Le coût est réel : JSON.parse les rejette encore, et les API, pipelines de journaux et files de messages n'acceptent généralement que du JSON standard. Votre commentaire est silencieusement supprimé ou erre quelque part en aval.
2. Mettez la note dans les données.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
Fonctionne partout, mais pollue le modèle : chaque consommateur doit savoir quelles clés ignorer, et votre définition de type gagne un champ qui n'est pas vraiment des données.
3. Utilisez une description de Schema. description est destiné aux humains et aux outils. Les validateurs l'exposent, les éditeurs l'affichent au survol, et il n'entre jamais dans la charge utile. C'est la seule option qui survit à la maintenance à long terme sans casser la compatibilité.
4. Changez le format de fichier. Si le fichier existe pour être édité à la main, YAML ou TOML prennent nativement en charge les commentaires. Se battre contre JSON ici est un effort gaspillé.
Choisir
| Situation | Réponse |
|---|---|
| Envoyé à un autre système, via une API ou une file | Pas de commentaires ; documentez dans le Schema ou une doc externe |
| Configuration lue seulement par des humains et des éditeurs | JSONC, avec une extension .jsonc |
| Besoin d'outillage universel et d'explication en ligne | JSON standard plus description de Schema |
| Longue configuration avec beaucoup d'annotation | Passer à YAML |
FAQ
Pourquoi un champ _comment pollue-t-il le modèle ?
Parce qu'il devient une partie des données. Chaque consommateur doit savoir quelles clés ignorer, et la définition de type gagne un champ qui n'est pas vraiment des données métier.
L'explication doit-elle vivre dans une description JSON Schema ?
Oui. description reste hors de la charge utile, tandis que les validateurs l'exposent et que les éditeurs l'affichent au survol, donc c'est la seule option qui survit à la maintenance à long terme sans casser la compatibilité.
JSONC ou JSON5 peuvent-ils être parsés par JSON.parse ?
Non. JSON.parse rejette encore les commentaires, et les API, pipelines de journaux et files de messages n'acceptent généralement que du JSON standard, donc le commentaire est supprimé ou erre quelque part en aval.
Outils
- Parseur JSON5 — collez une configuration commentée et voyez la structure résolue
- Formateur et validateur JSON — le JSON illégal est rapporté avec ligne et colonne, donc le commentaire fautif est évident