Commentaire dans le JSON : les alternatives sans erreur

La réponse sans détour

Non, un commentaire dans le JSON strict n’est pas possible. Les syntaxes `// commentaire` et `/* commentaire */` rendent le fichier invalide selon la grammaire JSON. Un navigateur avec `JSON.parse()`, une API qui attend du `application/json` ou de nombreux outils d’automatisation échoueront alors à le lire. Pour ajouter des notes sans casser la compatibilité, choisissez des métadonnées contrôlées, une documentation séparée ou un format étendu traité avant livraison.

L’extension du fichier ne change rien à cette règle. Renommer un fichier en `.json` ne donne pas le droit d’y placer des commentaires, pas plus que l’appeler « fichier de configuration ». À l’inverse, certains logiciels acceptent volontairement un dialecte comme JSONC ou JSON5 sous une extension `.json`. Cette tolérance appartient au logiciel concerné, non au standard JSON : elle doit donc être vérifiée pour chaque lecteur du fichier.

Pourquoi le JSON refuse les commentaires

Le JSON est un format d’échange de données volontairement étroit. Sa syntaxe définit précisément ce qu’un analyseur doit accepter : accolades, crochets, deux-points, virgules, valeurs et espaces blancs. Les commentaires n’en font pas partie. Ce cadre réduit les divergences entre langages et plateformes : un même document peut circuler entre un navigateur, un service Java, une application mobile et un outil métier sans interprétation particulière.

Cette contrainte crée une frontière utile entre la donnée et son explication. Un commentaire est pratique pour la personne qui édite le fichier, mais il n’a pas nécessairement de sens pour l’application qui le consomme. Si chaque bibliothèque décidait librement de conserver, retirer ou transmettre les commentaires, deux outils pourraient produire des résultats différents à partir du même document. Le JSON privilégie donc la portabilité au confort d’annotation.

• `// une note` — invalide dans un JSON strict, même s’il est placé seul sur une ligne.
• `/* une note */` — invalide également ; cette syntaxe appartient notamment à JavaScript et CSS, pas au JSON.
• Virgule finale — invalide après le dernier élément d’un objet ou d’un tableau JSON strict.
• Guillemets simples — invalides pour les chaînes et les noms de propriétés ; utilisez exclusivement des guillemets doubles.
• Clé non entourée de guillemets — invalide : écrivez `"port"` et non `port` dans un objet JSON.

Annoter sans quitter le JSON

La solution la plus compatible consiste à laisser le fichier en JSON strict et à placer les explications ailleurs : un README proche du fichier, une documentation d’API, un schéma JSON ou une page de conventions. C’est le meilleur choix dès que le document est envoyé à un tiers, publié sur le Web, importé dans plusieurs outils ou stocké comme donnée métier. L’explication ne risque alors ni de polluer le contrat, ni d’être interprétée comme une valeur exploitable.

Employer une clé de métadonnée avec prudence

Vous pouvez aussi ajouter une propriété telle que `"_comment": "Port du serveur de test"`. Le document reste alors parfaitement valide en JSON, car cette note est une simple chaîne de caractères associée à une clé. Mais ce n’est pas un vrai commentaire : elle sera reçue par tous les consommateurs, peut apparaître dans une interface, être indexée, exportée ou rejetée par une validation stricte. Convenez d’un préfixe et d’une règle de traitement avant de l’adopter.

JSONC et JSON5 : formats étendus

Quand un fichier est principalement écrit et relu par des humains, JSONC et JSON5 peuvent améliorer nettement le confort. JSONC désigne généralement du JSON enrichi de commentaires, souvent utilisé par certains outils d’édition et de configuration. JSON5 est un format distinct, plus permissif : il accepte notamment les commentaires, les virgules finales, les guillemets simples et, dans plusieurs cas, des identifiants non quotés. Aucun des deux n’est du JSON strict.

Ne confondez pas non plus JSONC avec un fichier JavaScript. JSONC reste destiné aux données et doit être lu par un parseur conçu pour lui. JSON5 étend davantage la syntaxe, ce qui le rend pratique à saisir mais moins interchangeable. Dans les deux cas, le fichier doit annoncer clairement sa convention dans le dépôt, et idéalement employer une extension explicite, par exemple `.jsonc` ou `.json5`, quand l’outil le permet.

Choisir selon le fichier concerné

Pour trancher, partez du consommateur le plus exigeant, pas de l’éditeur le plus souple. Un fichier d’options lu uniquement par votre application peut être du JSON5 si cette application le prévoit. Un fichier `package.json`, une réponse HTTP, un fichier importé par une administration, une plateforme SaaS ou un client mobile doit rester du JSON strict. Le fait qu’un éditeur colore correctement les commentaires ne garantit aucune compatibilité à l’exécution.

• Configuration locale d’IDE — utilisez JSONC seulement si l’outil documente ce mode et si le fichier ne part pas dans une API.
• Fichier de déploiement partagé — préférez JSON strict, un schéma et un README ; plusieurs systèmes peuvent le relire.
• Réponse d’API — envoyez exclusivement du JSON strict avec `application/json`, sans commentaire ni dialecte étendu.
• Données de catalogue ou import CSV converti — conservez les explications dans le modèle de données ou dans la documentation métier.
• Source de configuration complexe — autorisez JSONC ou JSON5 en amont, puis générez et contrôlez un `.json` final.
• Schéma de validation — utilisez `description` et, dans le schéma lui-même, `$comment` lorsque votre outillage le prend en compte.

Une propriété de type `description` ne doit pas servir de cachette à un commentaire technique si elle est affichée aux utilisateurs. Elle a du sens lorsqu’elle décrit réellement un produit, une règle ou un paramètre. À l’inverse, une note comme « ne pas modifier avant migration » relève de la documentation de maintenance. Séparer ces deux rôles évite que des consignes internes se retrouvent dans une interface cliente ou dans un export.

Mettre en place un flux fiable

La méthode la plus robuste pour bénéficier de commentaires sans abandonner le JSON consiste à distinguer le fichier source du fichier distribué. Les développeurs éditent un `.jsonc` ou un `.json5` ; une étape automatisée le lit avec le bon parseur, vérifie sa structure et produit un JSON strict. Les applications, scripts et services externes ne consomment ensuite que ce résultat. Cette séparation limite les erreurs de copier-coller et les incompatibilités tardives.

Conservez une source unique. Modifier à la main le fichier JSON généré et son équivalent JSONC mène presque toujours à une divergence. Faites du fichier commenté l’artefact éditable, puis régénérez le JSON strict à chaque livraison. Si vous devez versionner le résultat pour un outil externe, marquez-le clairement comme généré et interdisez sa modification manuelle dans les conventions du projet.

Erreurs fréquentes et cas particuliers

L’erreur la plus courante consiste à supprimer `//` avec une expression régulière avant de faire `JSON.parse()`. Cette approche casse les chaînes qui contiennent une URL comme `"https://exemple.fr"`, un chemin ou du texte incluant les mêmes caractères. Elle peut aussi retirer une portion de contenu légitime après un échappement. Un parseur JSONC ou JSON5 analyse le contexte syntaxique ; une expression régulière, elle, ne sait pas de façon fiable si elle lit une chaîne ou un commentaire.

Objets, tableaux et fichiers imposés

Dans un objet, une clé `_comment` reste techniquement possible, à condition que le contrat l’autorise. Dans un tableau homogène, ajouter une chaîne explicative au milieu des objets change le type de l’élément et peut provoquer une erreur ou un comportement inattendu. Évitez aussi d’entourer un tableau existant d’un objet `data` pour y ajouter une note : vous modifiez alors toute l’interface. Quand le format est imposé par un fournisseur, seul son contrat fait foi.

• Copier un exemple JSON5 — vérifiez les guillemets simples, les clés non quotées et les virgules finales avant de le coller dans un JSON strict.
• Faire confiance à l’extension `.json` — inspectez le parseur réel ; l’extension n’est qu’un nom de fichier.
• Ajouter `_comment` partout — centralisez les notes ou utilisez la documentation pour éviter de noyer les données.
• Publier du JSONC sur une API — convertissez-le d’abord ; un client standard ne comprend pas ce dialecte.
• Masquer un secret en commentaire — retirez-le du dépôt et des historiques, car un commentaire peut être conservé ou diffusé.

Coût, données sensibles et maintenance

Le format JSON, JSONC ou JSON5 n’entraîne pas de coût de licence par nature. Le coût réel est celui de l’outillage et des incidents évités : rédaction d’une convention, ajout d’un parseur, conversion dans l’intégration continue et tests. Pour un petit projet, cela représente souvent une tâche de configuration ponctuelle. Pour une API ou plusieurs équipes, ce temps est généralement moins coûteux qu’un incident de compatibilité chez un client ou lors d’un déploiement.

Il n’existe pas de saisonnalité propre au JSON : un fichier ne devient pas plus compatible selon la période de l’année. En revanche, planifiez les migrations de format en dehors des fenêtres de mise en production chargées, et testez-les avant un changement majeur d’IDE, de bibliothèque ou de plateforme. Inscrivez le dialecte autorisé dans les règles du dépôt ; cette décision survivra mieux aux arrivées dans l’équipe qu’une simple habitude orale.

La règle simple à retenir

Si vous devez échanger le fichier, gardez-le en JSON strict. Si vous devez surtout le lire et le modifier à la main, un fichier JSONC ou JSON5 est acceptable à condition que son parseur soit explicitement maîtrisé. Si vous avez besoin des deux, adoptez un source commenté et générez un JSON standard. C’est la solution qui préserve la lisibilité humaine sans transformer chaque consommateur en cas particulier.

• Besoin de compatibilité maximale — JSON strict, schéma de validation et documentation séparée.
• Besoin de notes locales — JSONC, seulement dans un outil qui l’annonce explicitement.
• Besoin de syntaxe plus souple — JSON5, avec un parseur dédié et une convention d’équipe.
• Besoin d’un fichier livré — conversion automatisée vers JSON strict avant publication.
• Besoin de sens métier — utilisez un vrai champ `description`, pas un commentaire déguisé.