RFC 8259: Pourquoi JSON n'autorise pas les commentaires

La réponse courte

Non. JSON ne supporte pas les commentaires. Ni les commentaires sur une ligne, ni les commentaires multi-lignes, ni aucun type de commentaire.

Ce n'est pas un oubli. C'est une décision de conception délibérée.

Si vous ajoutez un commentaire à un fichier JSON :

{
  // This is a comment
  "name": "Alice",
  "age": 30
}

Tout parser JSON standard rejettera ceci avec une erreur de syntaxe. Les caractères // ne sont pas une syntaxe JSON valide.

Idem pour les commentaires multi-lignes :

{
  /* This will also fail */
  "name": "Alice"
}

Ceci est du JSON invalide. Cela échouera dans chaque langage, chaque parser, chaque outil.

Pourquoi JSON n'autorise pas les commentaires (RFC 8259)

En consultant la spécification officielle qui régit l'échange de données, la réponse immédiate est claire : la norme json n'autorise pas les commentaires rfc 8259 interdit explicitement leur inclusion. La RFC 8259 sert de document d'ingénierie définitif pour la notation d'objets JavaScript à l'échelle mondiale, établissant les limites de syntaxe rigides que tous les analyseurs (parsers) modernes doivent respecter.

Lors du développement architectural initial du format, les annotations textuelles standards ont été activement envisagées mais finalement rejetées. À mesure que l'adoption se généralisait, le créateur du format, Douglas Crockford, a remarqué que les ingénieurs essayaient d'injecter des métadonnées et des instructions dans les structures de fichiers. La règle établissant que les commentaires json rfc 8259 ne sont pas autorisés a été strictement appliquée pour éviter une fragmentation catastrophique du standard.

Il a remarqué que des développeurs utilisaient incorrectement ces blocs de syntaxe pour héberger des directives d'analyse spécifiques, ce qui risquait de détruire totalement l'interopérabilité entre les différentes plateformes et langages de programmation. Si les annotations étaient restées, une charge utile générée par un serveur Node.js pourrait ne pas s'analyser correctement dans un backend Python ou Java en raison de comportements cachés inattendus.

Pour clarifier définitivement cette décision historique, Crockford a publié une déclaration expliquant son raisonnement technique :

« J'ai supprimé les commentaires de JSON parce que j'ai vu que les gens les utilisaient pour contenir des directives de parsing, une pratique qui aurait détruit l'interopérabilité. »

En interdisant complètement ces annotations et en établissant les directives strictes de la RFC, la spécification empêche efficacement les directives d'analyse cachées de casser les applications en production. Cette simplicité sans compromis garantit que toute charge utile JSON valide peut être analysée de manière sûre, sécurisée et uniforme par n'importe quel écosystème de programmation sans rencontrer d'erreurs de jetons (tokens) inattendues.

Mais j'ai besoin de commentaires dans mes fichiers JSON

C'est l'une des frustrations les plus courantes des développeurs. Vous avez un fichier de configuration, vous voulez expliquer ce que fait chaque paramètre, et JSON ne vous le permet pas.

Voici vos options réelles :

Option 1 : Utiliser une clé _comment

Ajoutez une clé qui décrit la valeur suivante :

{
  "_comment": "Database connection settings",
  "host": "localhost",
  "port": 5432,
  "_comment_timeout": "Timeout in milliseconds",
  "timeout": 3000
}

C'est techniquement du JSON valide. Les clés _comment sont simplement des propriétés de chaîne normales. Votre code applicatif les ignore simplement.

Avantages :

• JSON valide
• fonctionne avec tous les parsers
• lisible par les humains

Inconvénients :

• pollue les données avec des clés non-données
• pas de convention standard pour le nom de la clé
• certains schémas rejetteront les clés inconnues

Option 2 : Utiliser JSON5

JSON5 est une extension de JSON qui permet :

• les commentaires sur une ligne (//)
• les commentaires multi-lignes (/* */)
• les virgules finales
• les chaînes entre guillemets simples
• les clés sans guillemets

{
  // Database settings
  host: "localhost",
  port: 5432,
  timeout: 3000, // in milliseconds
}

Avantages :

• syntaxe naturelle
• supporte les vrais commentaires
• rétrocompatible avec JSON

Inconvénients :

• pas du JSON standard
• nécessite un parser JSON5
• non supporté par la plupart des APIs

Option 3 : Utiliser JSONC (JSON avec commentaires)

JSONC est le format utilisé par VS Code pour ses fichiers de paramètres (settings.json, tsconfig.json, launch.json). Il autorise les commentaires // et /* */ mais est par ailleurs du JSON standard.

{
  // Enable strict mode
  "strict": true,
  /* Compiler options
     for TypeScript */
  "target": "ES2020"
}

Avantages :

• supporté par VS Code, la configuration TypeScript, la configuration ESLint
• syntaxe familière
• largement utilisé dans l'outillage

Inconvénients :

• pas du JSON standard
• ne fonctionne pas avec JSON.parse()
• limité à des outils spécifiques qui le supportent

Option 4 : Utiliser YAML à la place

Si vous avez besoin d'un format de configuration avec des commentaires, YAML les supporte nativement :

# Database settings
host: localhost
port: 5432
timeout: 3000  # in milliseconds

YAML est conçu pour la configuration. JSON est conçu pour l'échange de données. Si vous avez besoin de commentaires, YAML pourrait être le bon format pour votre cas d'usage.

Option 5 : Utiliser un fichier de documentation séparé

Gardez votre JSON propre et mettez la documentation dans un fichier séparé :

config.json          ← données pures, pas de commentaires
config.README.md     ← explique ce que fait chaque paramètre

Cela garde votre JSON valide tout en fournissant une documentation lisible par les humains.

Qu'en est-il de tsconfig.json ?

Le tsconfig.json de TypeScript autorise les commentaires même si l'extension du fichier est .json. Cela fonctionne parce que TypeScript utilise son propre parser (parser JSONC) qui supprime les commentaires avant le traitement. Il n'est pas analysé par JSON.parse().

Cela s'applique aussi à :

• settings.json de VS Code
• .eslintrc.json d'ESLint
• Divers fichiers launch.json et tasks.json

Ces outils utilisent des parsers JSONC en interne. Les fichiers ressemblent à du JSON avec des commentaires, mais ils sont techniquement du JSONC, pas du JSON standard.

Erreurs courantes

Erreur 1 : Ajouter des commentaires et espérer que ça marche

{
  // This WILL break
  "name": "Alice"
}

JSON.parse() lancera :

SyntaxError: Unexpected token '/' at position 4

Il n'y a aucun paramètre, flag ou option pour faire accepter les commentaires par JSON.parse(). Cela échouera toujours.

Erreur 2 : Utiliser des commentaires hash

{
  # This is not valid either
  "name": "Alice"
}

Les commentaires hash fonctionnent en YAML, Python et dans les scripts shell. Ils ne fonctionnent pas en JSON.

Erreur 3 : Supposer que tous les fichiers .json sont du JSON standard

De nombreux outils utilisent l'extension .json pour des fichiers qui sont en fait du JSONC ou du JSON5. Ce n'est pas parce qu'un fichier a une extension .json et contient des commentaires qu'il s'agit de JSON valide.

Si vous copiez un tsconfig.json avec des commentaires et essayez de l'analyser avec JSON.parse(), cela échouera.

Supprimer les commentaires du JSON

Si vous recevez un fichier JSON avec des commentaires et devez l'analyser, vous devez d'abord supprimer les commentaires.

En JavaScript :

function stripJsonComments(jsonString) {
  return jsonString
    .replace(/\/\/.*$/gm, '')     // Remove single-line comments
    .replace(/\/\*[\s\S]*?\*\//g, ''); // Remove multi-line comments
}

const cleanJson = stripJsonComments(dirtyJson);
const data = JSON.parse(cleanJson);

Attention : Cette approche simple par regex peut casser si vos chaînes JSON contiennent les caractères // ou /*. Pour un usage en production, utilisez une bibliothèque d'analyse JSONC appropriée.

Formater du JSON en toute sécurité

Lorsque vous travaillez avec des fichiers JSON — avec ou sans commentaires — utilisez un formateur qui s'exécute entièrement dans votre navigateur. Si votre JSON contient des données de configuration, des réponses API ou des paramètres internes, vous ne voulez pas que ces données soient envoyées à un serveur tiers.

Le formateur JSON FmtDev traite tout localement. Vos données ne quittent jamais votre navigateur.

Points clés à retenir

1. JSON ne supporte pas les commentaires — c'est intentionnel, pas un bug
2. Douglas Crockford a supprimé les commentaires pour éviter l'abus de directives de parsing
3. Utilisez les clés _comment, JSON5, JSONC ou YAML si vous avez besoin de commentaires
4. tsconfig.json utilise JSONC, pas du JSON standard
5. JSON.parse() rejettera toujours les commentaires — sans exception
6. Si vous devez supprimer les commentaires, utilisez un parser JSONC approprié, pas une regex
7. Formatez et validez le JSON localement — n'envoyez jamais de données de configuration à des outils en ligne

Articles connexes

• Guide de formatage JSON
• Corriger les erreurs Unexpected Token dans JSON.parse
• Comment comparer des fichiers JSON
• Comment convertir un CSV en JSON
• JSON vs dictionnaire Python : quelle est la différence ?

Foire Aux Questions (FAQ)

Le JSON supporte-t-il les commentaires dans la RFC 8259 ?

Non. La spécification officielle du JSON (RFC 8259) ne supporte aucun type de commentaire, interdisant à la fois les annotations sur une seule ligne et les annotations multi-lignes. Les inclure déclenchera immédiatement une erreur d'analyse dans les processeurs JSON standards.