De JSON5 à JSONC : un formatage JSON plus tolérant

Quand un simple oubli de virgule vous fait passer la nuit à déboguer un fichier JSON, il est peut-être temps de rencontrer ses cousins plus indulgents — JSON5 et JSON with Comments (JSONC).

Qu’est-ce que JSON5 ?

JSON5 est une extension de JSON qui intègre des fonctionnalités d’ECMAScript 5.1 : clés sans guillemets, virgules finales, chaînes entre guillemets simples, commentaires et nombres hexadécimaux. Maintenu par la communauté, il rend les fichiers de configuration écrits à la main plus lisibles et tolérants que le JSON strict.

Qu’est-ce que JSONC ?

JSONC (JSON with Comments) est une extension minimale du JSON standard ajoutant les commentaires sur une ligne (//) et sur plusieurs lignes (/* */). Les virgules finales, elles, ne sont pas toujours acceptées : cela dépend du parseur. C’est le format natif des paramètres VS Code, de tsconfig.json et d’autres fichiers de configuration TypeScript.

Pourquoi avons-nous besoin d’un JSON « tolérant » ?

• Lisibilité : Le JSON strict refuse les commentaires, virgules finales, guillemets simples. Les fichiers de configuration deviennent opaques.
• Collaboration : Maintenir du JSON volumineux sans annotations rend les modifications fragiles.
• Réalisme DevOps : Kubernetes et CI/CD exigent souvent une fusion/génération dynamique ; une syntaxe flexible réduit les corrections manuelles.

JSON5 vs JSONC : comparaison

Fonctionnalité	JSON (RFC 8259)	JSONC	JSON5
Commentaires // et /* */	Non	Oui	Oui
Virgules finales	Non	Selon le parseur (voir ci-dessous)	Oui, une par objet ou tableau
Clés sans guillemets	Non	Non	Oui
Chaînes entre guillemets simples	Non	Non	Oui
Chaînes sur plusieurs lignes (saut de ligne échappé)	Non	Non	Oui
Nombres hexadécimaux (0x1F)	Non	Non	Oui
.5, 5., + en tête	Non	Non	Oui
Infinity, NaN	Non	Non	Oui
Nombres binaires (0b101)	Non	Non	Non
Spécification	RFC 8259 / ECMA-404	Aucun standard formel ; définie en pratique par VS Code et jsonc-parser	Spécification JSON5 1.0.0
Lisible par JSON.parse / json.loads natifs	Oui	Non	Non

Sources : la spécification JSON5, la documentation JSON de VS Code et la RFC 8259. Nous avons aussi exécuté JSON5.parse('{a: 0b101}') avec json5 2.2.3 : l’appel échoue avec JSON5: invalid character 'b' at 1:6.

Distinction clé : JSON5 ressemble à un littéral d’objet JavaScript, tandis que JSONC reste du JSON ordinaire qui tolère les commentaires : les clés comme les chaînes doivent toujours être entre guillemets doubles.

Virgules finales en JSONC : tout dépend du parseur

JSONC n’a pas de spécification officielle. Microsoft l’a introduit de manière informelle pour les fichiers de configuration de VS Code et a publié jsonc-parser dans la foulée. Un brouillon communautaire hébergé sur jsonc.org tente de le formaliser, et se contente d’indiquer que les parseurs « MAY support trailing commas » (peuvent accepter les virgules finales). Dans les faits, les outils ne sont pas d’accord :

Parseur ou outil	Virgule finale	Source
VS Code, mode JSON with Comments	Acceptée, avec un avertissement	Documentation VS Code
jsonc-parser 3.3.1, options par défaut	Signalée par des erreurs PropertyNameExpected / ValueExpected, mais une valeur est quand même renvoyée	Test plus bas
jsonc-parser 3.3.1, allowTrailingComma: true	Acceptée	Test plus bas
TypeScript 5.9.3 (tsc -p)	Acceptée	Test sur l’exemple tsconfig ci-dessous
Deno (deno.jsonc)	Acceptée	Documentation de configuration de Deno

Si votre fichier doit être accepté par tous les lecteurs JSONC, n’y mettez pas de virgules finales.

Exemples de syntaxe

JSON classique (strict)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

JSON5

Un fichier JSON5, config.json5 :

// config de développement
{
  name: 'go-tools',
  port: 0x1F90,       // 8080 en hexadécimal
  tags: ['json', 'json5',],
}

JSONC

Un fichier JSONC, tsconfig.json :

{
  // vérification de types stricte
  "compilerOptions": {
    "strict": true,
    "target": "ES2022", /* sortie moderne */
  },
  "include": ["src"],
}

Quel format utilise votre fichier ?

L’extension ne suffit pas : un fichier .json peut très bien être lu comme du JSONC ou du JSON5. Consultez ce tableau, puis la documentation de l’outil qui lit le fichier.

Fichier	Format	Remarques	Source
tsconfig.json, jsconfig.json, tsconfig.*.json	JSONC	VS Code les ouvre en mode JSONC ; tsc 5.9.3 accepte commentaires et virgules finales	Code source de VS Code (typescript-basics), notre test
.vscode/settings.json, tasks.json, launch.json	JSONC	Cités comme fichiers JSON with Comments	Documentation VS Code
devcontainer.json	JSONC	La spécification le décrit comme « a JSON with Comments file » (un fichier JSON with Comments)	Spécification Dev Container
deno.jsonc	JSONC	« with deno.jsonc you can add comments and trailing commas » (avec deno.jsonc, vous pouvez ajouter des commentaires et des virgules finales)	Documentation Deno
babel.config.json, .babelrc.json	JSON5, malgré l’extension .json	Babel les analyse comme du JSON5 ; VS Code les colore comme du JSONC	Documentation Babel, code source de VS Code
renovate.json5, .renovaterc.json5	JSON5	renovate.json accepte aussi le JSONC	Documentation Renovate
Tout fichier *.json5	JSON5	—	—
package.json	JSON strict	npm : « It must be actual JSON, not just a JavaScript object literal. » (du vrai JSON, pas un simple littéral d’objet JavaScript)	Documentation npm, notre test

Babel ne cherche pas de fichier babel.config.json5 : .json5 ne figure pas parmi les extensions qu’il documente. Ce sont les variantes en .json qu’il lit comme du JSON5.

Les erreurs que vous verrez, mot pour mot

Nous avons soumis deux petits fichiers à chaque environnement d’exécution. comment.json contient un commentaire :

{
  // port du serveur de dev
  "port": 8080
}

trailing.json contient une virgule finale :

{
  "port": 8080,
}

Node.js 26.10.0, JSON.parse (Chrome Headless Shell 156 affiche exactement le même texte, puisque les deux reposent sur V8) :

comment.json  -> SyntaxError: Expected property name or '}' in JSON at position 4 (line 2 column 3)
trailing.json -> SyntaxError: Expected double-quoted property name in JSON at position 18 (line 3 column 1)

Python 3.13.5, json.loads :

comment.json  -> json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 2 column 3 (char 4)
trailing.json -> json.decoder.JSONDecodeError: Illegal trailing comma before end of object: line 2 column 15 (char 16)

jq 1.7 :

comment.json  -> jq: parse error: Invalid numeric literal at line 2, column 5
trailing.json -> jq: parse error: Expected another key-value pair at line 3, column 1

npm 11.19.1, avec une ligne // comment dans package.json :

npm error code EJSONPARSE
npm error JSON.parse Invalid package.json: JSONParseError: Expected property name or '}' in JSON at position 4 (line 2 column 3) while parsing near "{\n  // comment\n  \"name\":..."
npm error JSON.parse Failed to parse JSON data.
npm error JSON.parse Note: package.json must be actual JSON, not just JavaScript.

Comment les lire :

• position 4 (line 2 column 3) désigne le premier / du commentaire. Quand l’erreur tombe au début d’une ligne qui commence par // ou /*, le fichier est presque certainement du JSONC ou du JSON5.
• Sur une virgule finale, V8 et Python ne pointent pas au même endroit. V8 signale l’accolade fermante } (ligne 3), tandis que Python 3.13.5 signale la virgule elle-même (ligne 2, colonne 15). D’autres versions peuvent formuler ces messages autrement ; le texte ci-dessus est exactement celui qu’ont affiché ces versions.
• Si l’erreur cite un caractère que vous ne voyez pas, comme dans le message de Node 26 Unexpected token '', "{}" is not valid JSON (les deux paires de guillemets contiennent en réalité un U+FEFF invisible), le fichier commence très probablement par une marque d’ordre des octets (BOM) invisible, et non par un commentaire. Voir BOM UTF-8 : corriger les erreurs JSON.parse.

Convertir du JSONC ou du JSON5 en JSON standard

La conversion supprime tous les commentaires, car JSON n’a nulle part où les conserver. Gardez le fichier commenté comme source et traitez la sortie .json comme un artefact généré.

Node.js : du JSON5 au JSON avec json5

// json5-to-json.mjs (prérequis : npm install json5)
import { readFileSync, writeFileSync } from 'node:fs';
import JSON5 from 'json5';

const data = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(data, null, 2) + '\n');

Exécuté avec json5 2.2.3 sur l’exemple JSON5 ci-dessus, config.json devient :

{
  "name": "go-tools",
  "port": 8080,
  "tags": [
    "json",
    "json5"
  ]
}

Node.js : du JSONC au JSON avec jsonc-parser

jsonc-parser est le parseur de Microsoft pour le JSON avec commentaires. Sa fonction parse() ne lève pas d’exception en cas d’erreur de syntaxe : elle consigne les problèmes dans un tableau errors et renvoie malgré tout la meilleure valeur possible. C’est donc à vous de vérifier ce tableau :

// jsonc-to-json.mjs (prérequis : npm install jsonc-parser)
import { readFileSync } from 'node:fs';
import { parse, printParseErrorCode } from 'jsonc-parser';

const errors = [];
const data = parse(readFileSync('tsconfig.json', 'utf8'), errors, {
  allowTrailingComma: true,
});
if (errors.length > 0) {
  for (const e of errors) console.error(printParseErrorCode(e.error), 'at offset', e.offset);
  process.exit(1);
}
console.log(JSON.stringify(data, null, 2));

Avec jsonc-parser 3.3.1 et l’exemple tsconfig ci-dessus, ce script affiche un JSON propre et se termine avec le code 0. Sans allowTrailingComma: true, le même fichier signale PropertyNameExpected et ValueExpected sur l’accolade } qui suit immédiatement chaque virgule finale.

Python : le package json5

Le module json de la bibliothèque standard n’a aucune option pour les commentaires. Le package json5 lit le JSON5, et donc aussi le JSONC, puisque commentaires et virgules finales sont tous deux valides en JSON5 :

# prérequis : pip install json5
import json

import json5

with open("tsconfig.json", encoding="utf-8") as f:
    data = json5.load(f)

print(json.dumps(data, indent=2, ensure_ascii=False))

Testé avec Python 3.13.5 et json5 0.17.3, ce script affiche le même JSON que la version Node.

En ligne de commande : la CLI json5

Le package npm json5 fournit une CLI qui convertit en JSON et valide. Elle lit aussi les fichiers JSONC :

npx json5 config.json5                      # JSON compact sur la sortie standard
npx json5 -s 2 -o config.json config.json5  # indenté, écrit dans un fichier
npx json5 -v tsconfig.json                  # validation seule ; code de sortie 1 en cas d'erreur de syntaxe

Comme -v se termine avec le code 1 en cas d’erreur de syntaxe, la même commande peut servir d’étape de CI pour vérifier les fichiers JSON5 ou JSONC édités à la main.

jq ne vous sera d’aucune aide ici : comme on l’a vu plus haut, jq 1.7 s’arrête au premier commentaire.

Attention à Infinity et NaN

JSON5 autorise Infinity et NaN, mais JSON n’a aucun moyen de les écrire, et les deux langages ne gèrent pas ce cas de la même façon :

JSON.stringify(JSON5.parse('{a: Infinity, b: NaN}'));
// '{"a":null,"b":null}'  (devient null sans prévenir)

json.dumps(json5.loads('{a: Infinity, b: NaN}'))
# '{"a": Infinity, "b": NaN}'  (sortie qui n'est pas du JSON valide)
json.dumps(json5.loads('{a: Infinity}'), allow_nan=False)
# ValueError: Out of range float values are not JSON compliant: inf

Si un fichier JSON5 peut en contenir, passez allow_nan=False en Python, ou vérifiez leur présence avant de convertir. Les chaînes JSON5 entre guillemets simples qui contiennent " ou des barres obliques inverses sont ré-échappées par JSON.stringify. Les règles sont détaillées dans le guide d’échappement des chaînes JSON.

Valider le JSON converti

Une fois la conversion faite, collez la sortie dans le Formateur JSON pour la valider et l’indenter. Il fonctionne dans votre navigateur.

Attention : le formateur n’accepte que du JSON strict. Il analyse le texte avec le JSON.parse du navigateur ; un fichier JSONC ou JSON5 collé tel quel échoue donc sur une erreur de syntaxe, avec la ligne et la colonne où l’analyse s’est arrêtée. Convertissez d’abord, validez ensuite.

Quand ne pas utiliser JSONC ou JSON5

• Payloads d’API et échange de données. La RFC 8259 exige qu’un générateur JSON « MUST strictly conform to the JSON grammar » (se conforme strictement à la grammaire JSON). En réception, on trouve généralement JSON.parse ou json.loads, et tous deux rejettent les commentaires.
• package.json. npm exige du JSON strict. Un seul commentaire suffit à faire échouer des commandes npm comme npm run avec EJSONPARSE.
• Fichiers lus par des outils que vous ne maîtrisez pas. Le require('./tsconfig.json') de Node passe par le parseur JSON strict et échoue sur un tsconfig commenté (SyntaxError: …tsconfig.json: Expected property name or '}' in JSON at position 4). Tout script qui lit un fichier JSONC a besoin d’un parseur JSONC.
• Un fichier .json devenu JSONC sans le dire. La documentation de Renovate recommande un fichier .jsonc plutôt qu’un fichier .json avec commentaires, car ce dernier « can cause issues with editors and syntax highlighting » (peut poser problème aux éditeurs et à la coloration syntaxique). Une extension explicite indique à chaque outil à quoi s’attendre.

Si vous choisissez un format de configuration de zéro et voulez des commentaires partout, TOML et YAML les prennent en charge nativement. Voir TOML vs JSON vs YAML.

Conseils pratiques & pièges

1. Conversion avant production

• Les navigateurs requièrent du JSON strict pour JSON.parse().
• Convertir au moment du build, comme le montre la section sur la conversion ci-dessus.

2. Sécurité & fiabilité

• Une syntaxe tolérante peut dissimuler des champs indésirables ; valider avec JSON Schema ou zod avant exposition d’API.

3. Convention d’équipe

• Documenter que les fichiers *.json5 sont réservés aux configs ; les paquets publiés doivent contenir du .json strict.
• Uniformiser les règles Prettier pour éviter les diffs inutiles.

4. Performance

• Le parsing JSON5/JSONC ajoute des dépendances et un léger overhead — acceptable pour CLI & dev, à mesurer en production.

Questions Fréquentes

Quelle est la différence entre JSON5 et JSONC ?

JSONC, c’est le JSON standard plus les commentaires // et /* */ ; la prise en charge des virgules finales dépend du parseur. JSON5 va plus loin avec la syntaxe ES5.1 : clés sans guillemets, guillemets simples, nombres hexadécimaux, Infinity/NaN et virgules finales. Un fichier JSONC valide est généralement du JSON5 valide, mais l’inverse n’est pas vrai. Choisissez JSONC quand les commentaires suffisent ; choisissez JSON5 quand vous avez besoin d’une syntaxe plus riche.

Peut-on utiliser JSON5 ou JSONC dans les API de production ?

Non — JSON5 et JSONC sont conçus pour les fichiers de configuration, pas pour l’échange de données. Les API doivent utiliser du JSON standard (RFC 8259) pour une interopérabilité maximale. Réservez JSON5/JSONC aux fichiers de configuration locaux comme tsconfig.json, .vscode/settings.json ou la configuration d’environnement où la lisibilité humaine prime sur le parsing machine.

VS Code supporte-t-il JSON5 nativement ?

Pas nativement. L’extension JSON intégrée à VS Code enregistre notamment les langages json, jsonc et jsonl, mais pas json5 : pour avoir la coloration syntaxique des fichiers .json5, il faut une extension du marketplace. JSONC, en revanche, est intégré : les paramètres, tasks.json, launch.json et tsconfig.json s’ouvrent tous en mode JSON with Comments.

Comment convertir du JSON5 en JSON standard ?

Utilisez le package npm json5 : JSON5.parse() lit le JSON5, puis JSON.stringify() produit du JSON standard. En CLI, exécutez npx json5 < input.json5 > output.json. Les commentaires sont perdus au passage, et JSON.stringify transforme Infinity et NaN en null : vérifiez leur présence avant de convertir. Des outils en ligne comme notre JSON Formatter peuvent également valider la sortie convertie pour garantir l’exactitude.

JSONC est-il identique à JSON with Comments ?

Oui. « JSON with Comments » est le nom du mode de langage de VS Code, et jsonc en est l’identifiant de langage et l’extension de fichier. C’est le format utilisé par VS Code, TypeScript (tsconfig.json) et d’autres outils Microsoft. Il n’existe pas de standard formel : jsonc.org héberge un brouillon communautaire fondé sur ce que jsonc-parser accepte par défaut. JSONC ajoute au JSON standard les commentaires // et /* */ ; la prise en charge des virgules finales, elle, dépend du parseur. Les parseurs suppriment les commentaires avant traitement, donc la structure de données résultante est identique au JSON standard.

Pour plus d’outils de développement en navigateur, y compris l’encodage Base64, la génération de hachage et la conversion de timestamps, consultez notre Guide essentiel des outils de développement.

Conclusion

Trouver l’équilibre entre lisibilité et rigueur est un défi classique du développement. JSON5 et JSONC améliorent l’expérience d’écriture, et avec un pipeline de build et une validation appropriés, vous pouvez profiter des avantages du « JSON tolérant » en toute sécurité.

Références

• Format d’échange de données JSON5 1.0.0
• VS Code : JSON with Comments
• TypeScript : qu’est-ce qu’un tsconfig.json
• RFC 8259 : le format d’échange de données JavaScript Object Notation (JSON)
• Spécification JSONC (brouillon communautaire)
• jsonc-parser
• Babel : fichiers de configuration
• Référence des métadonnées Dev Container