JSON avec commentaires

JSONC (JSON with Comments) étend le JSON standard pour permettre les commentaires de style JavaScript. De nombreux outils de développement utilisent JSONC pour les fichiers de configuration où les commentaires aident à documenter les paramètres. Cet analyseur supprime les commentaires pour produire du JSON valide tout en préservant la structure des données.

Specifications

• jsonc-parser (VS Code)
• TypeScript tsconfig.json

Cas d'utilisation courants

• Analyser les fichiers tsconfig.json et jsconfig.json pour les projets TypeScript/JavaScript
• Lire les fichiers settings.json et la configuration des extensions VS Code
• Traiter les fichiers de configuration Cloudflare wrangler.jsonc
• Éditer les configurations ESLint, Prettier et autres outils avec documentation en ligne

Fonctionnalites

• Analyser les commentaires sur une ligne (// commentaire)
• Analyser les commentaires sur plusieurs lignes (/* commentaire */)
• Gérer les virgules finales (courantes dans les fichiers JSONC)
• Supprimer les commentaires pour produire une sortie JSON valide
• Toutes les fonctionnalités standard de l'analyseur JSON (vue arborescente, conversion)

Exemples

{
  // Compiler options for the project
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    /* Enable all strict type checking options */
    "strict": true
  }
}

Conseils

• VS Code, TypeScript et de nombreux outils modernes prennent en charge JSONC nativement.
• Lors du partage de configuration, vérifiez si les outils des destinataires prennent en charge les commentaires.
• Convertissez en JSON standard en supprimant les commentaires lorsque les outils exigent du JSON strict.

Comprendre JSON avec commentaires

JSONC (JSON with Comments) est une extension du JSON standard qui autorise les commentaires de style JavaScript sur une ligne (//) et multi-lignes (/* */), ainsi que les virgules finales après le dernier élément dans les tableaux et objets. Bien que ce ne soit pas un standard officiel, JSONC est devenu le format de facto pour les fichiers de configuration destinés aux développeurs où la documentation en ligne améliore la maintenabilité.

Microsoft a popularisé JSONC via Visual Studio Code, qui l'utilise pour settings.json, keybindings.json, launch.json et extensions.json. Les fichiers tsconfig.json de TypeScript et jsconfig.json de JavaScript sont des fichiers JSONC, tout comme de nombreux fichiers de configuration ESLint, Prettier et Babel lorsqu'ils utilisent l'extension .json. Le wrangler.jsonc de Cloudflare utilise explicitement l'extension .jsonc pour signaler le support des commentaires.

L'avantage principal de JSONC par rapport au JSON brut est la documentation. Les fichiers de configuration contiennent souvent des paramètres dont l'objectif n'est pas évident à partir du nom de la clé seul. Les commentaires permettent aux développeurs d'expliquer pourquoi un paramètre existe, quelles sont les valeurs valides et quelles sont les conséquences des modifications. Les virgules finales réduisent le bruit dans le contrôle de version en permettant au dernier élément d'avoir le même format que tous les autres, de sorte que l'ajout d'un nouvel élément ne montre qu'une ligne modifiée dans un diff au lieu de deux.

Sous le capot, les analyseurs JSONC fonctionnent en supprimant les commentaires et les virgules finales avant de passer le résultat à un analyseur JSON standard. Cela signifie que le modèle de données est identique à JSON — les commentaires sont des métadonnées pour les humains, pas des données pour les programmes. Lors de la conversion de JSONC en JSON pour des outils qui exigent une conformité JSON stricte, les commentaires sont simplement supprimés. La bibliothèque node-jsonc-parser de Microsoft, utilisée dans VS Code, est l'implémentation de référence pour l'analyse JSONC.

JSONC n'est pas un standard officiel défini par une RFC ou une spécification ECMA. C'est une convention popularisée par Microsoft via VS Code et TypeScript, avec un comportement bien défini par la bibliothèque jsonc-parser qui sert d'implémentation de référence. Les autres outils qui prennent en charge JSONC — ESLint, Prettier et divers éditeurs — suivent les mêmes conventions pour les commentaires sur une ligne, les commentaires multi-lignes et les virgules finales. Les fichiers JSONC courants incluent tsconfig.json et jsconfig.json (TypeScript/JavaScript), les fichiers de paramètres VS Code (settings.json, launch.json, tasks.json, keybindings.json), wrangler.jsonc (Cloudflare Workers), devcontainer.json (VS Code Dev Containers) et diverses autres configurations d'outils. Tout fichier JSON principalement édité par des développeurs qui pourrait bénéficier de commentaires prend probablement en charge JSONC.

JSONC ne doit être utilisé que pour les fichiers de configuration lus par des outils avec un support JSONC explicite. Les réponses API, le stockage de données et la communication inter-services doivent toujours utiliser du JSON standard, car la plupart des analyseurs JSON rejetteront les commentaires comme des erreurs de syntaxe. Pour traiter un fichier de configuration JSONC programmatiquement avec un analyseur JSON standard, supprimez d'abord les commentaires en utilisant une bibliothèque compatible JSONC.

JSONC est plus conservateur que JSON5, qui est un sur-ensemble plus étendu de JSON. Alors que JSONC n'ajoute que les commentaires et les virgules finales, JSON5 autorise également les chaînes entre guillemets simples, les clés d'objet sans guillemets, les nombres hexadécimaux, les points décimaux en début et fin, Infinity et NaN, et les chaînes multi-lignes. JSONC a un support plus large dans l'écosystème des développeurs, tandis que JSON5 est utilisé dans des fichiers de configuration spécifiques comme le babel.config.json5 de Babel mais a une adoption plus restreinte dans l'ensemble.