JSON peut-il avoir des commentaires ? La réponse complète

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

Douglas Crockford, le créateur de JSON, a intentionnellement supprimé les commentaires de la spécification. Il a expliqué publiquement son raisonnement :

« 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é. »

La crainte était que si JSON supportait les commentaires, les développeurs et les outils commenceraient à intégrer des instructions dans les commentaires (comme des indications de parser, des directives de prétraitement ou des métadonnées). Différents outils les interpréteraient différemment, brisant la compatibilité universelle qui rend JSON précieux.

JSON a été conçu comme un format d'échange de données pur — rien de plus. Il transporte des données entre systèmes. Ce n'est ni un langage de configuration, ni un langage de programmation, ni un format de document.

En gardant la spécification extrêmement simple (pas de commentaires, pas de virgules finales, pas de guillemets simples), JSON reste universellement analysable par chaque langage et chaque plateforme sans ambiguïté.

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 ?