JSON5 en JSONC formatteren: een toegeeflijkere JSON-aanpak

Houdt strikte JSON je ‘s nachts wakker door één ontbrekende komma? Maak kennis met zijn toegeeflijkere neven — JSON5 en JSON with Comments (JSONC).

Wat is JSON5?

JSON5 is een uitbreiding van JSON die functies uit ECMAScript 5.1 overneemt, zoals sleutels zonder aanhalingstekens, afsluitende komma’s, strings met enkele aanhalingstekens, commentaar en hexadecimale getallen. Het wordt beheerd door de community en is ontworpen om handgeschreven configuratiebestanden leesbaarder en toegeeflijker te maken dan strikte JSON.

Wat is JSONC?

JSONC (JSON with Comments) is een minimale uitbreiding van standaard JSON die ondersteuning toevoegt voor regelcommentaar (//) en blokcommentaar (/* */). Of afsluitende komma’s ook zijn toegestaan, hangt af van de parser. Het is het standaardformaat voor VS Code-instellingen, tsconfig.json en andere TypeScript-configuratiebestanden.

Waarom we “toegeeflijke” JSON nodig hebben

Leesbaarheidsproblemen: Standaard JSON staat geen commentaar, afsluitende komma’s of enkele aanhalingstekens toe, wat de leesbaarheid in configuraties en demo’s vermindert.
Samenwerken in teams: Grote JSON-bestanden zonder inline-notities zijn moeilijk te onderhouden; één kleine wijziging kan het hele bestand ongeldig maken.
DevOps in de praktijk: Kubernetes en CI/CD-pipelines voegen regelmatig JSON on the fly samen of genereren het; toegeeflijke syntax vermindert handmatige correcties aanzienlijk.

JSON5 versus JSONC in één oogopslag

Functie	JSON (RFC 8259)	JSONC	JSON5
`//`- en `/* */`-commentaar	Nee	Ja	Ja
Afsluitende komma’s	Nee	Hangt af van de parser (zie hieronder)	Ja, één per object of array
Sleutels zonder aanhalingstekens	Nee	Nee	Ja
Strings met enkele aanhalingstekens	Nee	Nee	Ja
Strings over meerdere regels (via een geëscapet regeleinde)	Nee	Nee	Ja
Hexadecimale getallen (`0x1F`)	Nee	Nee	Ja
`.5`, `5.`, een `+` vooraan	Nee	Nee	Ja
`Infinity`, `NaN`	Nee	Nee	Ja
Binaire getallen (`0b101`)	Nee	Nee	Nee
Specificatie	RFC 8259 / ECMA-404	Geen formele standaard; in de praktijk vastgelegd door VS Code en `jsonc-parser`	JSON5-specificatie 1.0.0
Leesbaar met de ingebouwde `JSON.parse` / `json.loads`	Ja	Nee	Nee

Bronnen: de JSON5-specificatie, de JSON-documentatie van VS Code en RFC 8259. Daarnaast hebben we JSON5.parse('{a: 0b101}') uitgevoerd met json5 2.2.3; dat mislukt met JSON5: invalid character 'b' at 1:6.

In één zin: JSON5 voelt als een JavaScript object literal, terwijl JSONC gewoon JSON is die commentaar verdraagt — sleutels en strings moeten nog steeds tussen dubbele aanhalingstekens staan.

Syntaxisvoorbeelden

Standaard JSON (strikt)

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

JSON5-voorbeeld

Een JSON5-bestand, config.json5:

// ontwikkelconfiguratie
{
  name: 'go-tools',
  port: 0x1F90,       // 8080 in hexadecimale notatie
  tags: ['json', 'json5',],
}

JSONC-voorbeeld

Een JSONC-bestand, tsconfig.json:

{
  // strikte typecontrole
  "compilerOptions": {
    "strict": true,
    "target": "ES2022", /* moderne output */
  },
  "include": ["src"],
}

Afsluitende komma’s in JSONC hangen af van de parser

JSONC heeft geen officiële specificatie. Microsoft introduceerde het informeel voor de configuratiebestanden van VS Code en bracht er jsonc-parser bij uit. Een communityconcept op jsonc.org probeert het formaat vast te leggen, maar zegt over afsluitende komma’s alleen dat parsers ze “MAY support trailing commas” (mogen ondersteunen). In de praktijk verschillen tools van elkaar:

Parser of tool	Afsluitende komma	Bron
VS Code, modus JSON with Comments	Geaccepteerd, met een waarschuwing	VS Code-documentatie
`jsonc-parser` 3.3.1, standaardopties	Gemeld als fouten `PropertyNameExpected` / `ValueExpected`, maar er komt toch een waarde terug	Eigen test, zie hieronder
`jsonc-parser` 3.3.1, `allowTrailingComma: true`	Geaccepteerd	Eigen test, zie hieronder
TypeScript 5.9.3 (`tsc -p`)	Geaccepteerd	Getest op de tsconfig hierboven
Deno (`deno.jsonc`)	Geaccepteerd	Configuratiedocumentatie van Deno

Wil je een bestand dat elke JSONC-lezer accepteert, laat afsluitende komma’s dan weg.

Welk formaat heeft je bestand?

Aan de extensie alleen zie je het niet: ook een .json-bestand kan als JSONC of JSON5 worden ingelezen. Kijk eerst in deze tabel en daarna in de documentatie van de tool die het bestand inleest.

Bestand	Formaat	Toelichting	Bron
`tsconfig.json`, `jsconfig.json`, `tsconfig.*.json`	JSONC	VS Code opent ze in JSONC-modus; `tsc` 5.9.3 accepteert commentaar en afsluitende komma’s	VS Code-broncode (`typescript-basics`), eigen test
`.vscode/settings.json`, `tasks.json`, `launch.json`	JSONC	Vermeld als JSON with Comments-bestanden	VS Code-documentatie
`devcontainer.json`	JSONC	De specificatie noemt het “a JSON with Comments file”	Dev Container-specificatie
`deno.jsonc`	JSONC	“with `deno.jsonc` you can add comments and trailing commas” (met `deno.jsonc` kun je commentaar en afsluitende komma’s toevoegen)	Deno-documentatie
`babel.config.json`, `.babelrc.json`	JSON5, ondanks de extensie `.json`	Babel leest ze in als JSON5; VS Code toont ze met JSONC-syntaxiskleuring	Babel-documentatie, VS Code-broncode
`renovate.json5`, `.renovaterc.json5`	JSON5	`renovate.json` accepteert ook JSONC	Renovate-documentatie
Elk `*.json5`-bestand	JSON5	—	—
`package.json`	Strikte JSON	npm: “It must be actual JSON, not just a JavaScript object literal.” (Het moet echte JSON zijn, niet zomaar een JavaScript object literal.)	npm-documentatie, eigen test

Babel zoekt niet naar een bestand babel.config.json5: .json5 staat niet tussen de gedocumenteerde extensies. Juist de .json-varianten leest Babel als JSON5.

De foutmeldingen die je te zien krijgt, letterlijk

We hebben elke runtime twee kleine bestanden laten inlezen. comment.json bevat commentaar:

{
  // poort van de ontwikkelserver
  "port": 8080
}

trailing.json heeft een afsluitende komma:

{
  "port": 8080,
}

Node.js 26.10.0, JSON.parse (Chrome Headless Shell 156 geeft dezelfde tekst, omdat beide V8 gebruiken):

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, met een regel // comment in 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.

Zo lees je ze:

position 4 (line 2 column 3) wijst naar de eerste / van het commentaar. Valt de fout aan het begin van een regel die met // of /* begint, dan is het bestand vrijwel zeker JSONC of JSON5.
Bij afsluitende komma’s wijzen V8 en Python naar verschillende plekken. V8 meldt de sluitende } (regel 3), terwijl Python 3.13.5 de komma zelf aanwijst (regel 2, kolom 15). Andere versies kunnen het anders formuleren; de tekst hierboven is precies wat deze versies afdrukten.
Citeert de foutmelding een teken dat je niet ziet, zoals in Unexpected token '', "{}" is not valid JSON van Node 26 (tussen beide paren aanhalingstekens staat in werkelijkheid een onzichtbare U+FEFF), dan begint het bestand hoogstwaarschijnlijk met een onzichtbare byte order mark en niet met commentaar. Zie UTF-8 BOM en JSON-parsefouten.

JSONC of JSON5 omzetten naar standaard JSON

Bij het omzetten verdwijnt al het commentaar, want JSON heeft er geen plek voor. Houd het bestand met commentaar als bron en behandel de .json-output als gegenereerd bestand.

Node.js: JSON5 naar JSON met `json5`

// json5-to-json.mjs (installeren met: 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');

Met json5 2.2.3 op het JSON5-voorbeeld hierboven ziet config.json er zo uit:

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

Node.js: JSONC naar JSON met `jsonc-parser`

jsonc-parser is de parser van Microsoft voor JSON with Comments. Bij syntaxisfouten gooit parse() geen fout. De functie verzamelt problemen in een array errors en geeft toch zo goed mogelijk een waarde terug, dus die array moet je zelf controleren:

// jsonc-to-json.mjs (installeren met: 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));

Met jsonc-parser 3.3.1 en het tsconfig-voorbeeld hierboven drukt dit schone JSON af en eindigt het met exitcode 0. Zonder allowTrailingComma: true meldt hetzelfde bestand PropertyNameExpected en ValueExpected bij de } direct na elke afsluitende komma.

Python: het pakket `json5`

De module json uit de standaardbibliotheek heeft geen optie voor commentaar. Het pakket json5 leest JSON5 in, en daarmee ook JSONC, want commentaar en afsluitende komma’s zijn allebei geldige JSON5:

# installeren met: 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))

Getest met Python 3.13.5 en json5 0.17.3: dit drukt dezelfde JSON af als de Node-versie.

Commandoregel: de `json5`-CLI

Het npm-pakket json5 bevat een CLI die naar JSON omzet en valideert. Die leest ook JSONC-bestanden:

npx json5 config.json5                      # compacte JSON naar stdout
npx json5 -s 2 -o config.json config.json5  # ingesprongen, naar een bestand geschreven
npx json5 -v tsconfig.json                  # alleen valideren; exitcode 1 bij een syntaxisfout

Omdat -v bij een syntaxisfout eindigt met exitcode 1, werkt hetzelfde commando als CI-stap die handmatig bewerkte JSON5- of JSONC-bestanden controleert.

Met jq kom je hier niet verder: zoals hierboven te zien is, stopt jq 1.7 bij de eerste commentaarregel.

Pas op met `Infinity` en `NaN`

JSON5 staat Infinity en NaN toe, maar JSON kan ze niet weergeven, en de twee talen gaan daar verschillend mee om:

JSON.stringify(JSON5.parse('{a: Infinity, b: NaN}'));
// '{"a":null,"b":null}'  (wordt ongemerkt null)

json.dumps(json5.loads('{a: Infinity, b: NaN}'))
# '{"a": Infinity, "b": NaN}'  (output die geen geldige JSON is)
json.dumps(json5.loads('{a: Infinity}'), allow_nan=False)
# ValueError: Out of range float values are not JSON compliant: inf

Kan een JSON5-bestand ze bevatten, geef in Python dan allow_nan=False mee of controleer er vóór het omzetten op. JSON5-strings met enkele aanhalingstekens die " of backslashes bevatten, worden door JSON.stringify opnieuw geëscapet. De regels staan in de gids over het escapen van JSON-strings.

De omgezette JSON valideren

Plak de output na het omzetten in de JSON Formatter om hem te valideren en overzichtelijk te formatteren. De tool draait in je browser.

Let op: de formatter accepteert alleen strikte JSON. Hij leest de invoer in met JSON.parse van de browser, dus een JSONC- of JSON5-bestand dat je ongewijzigd plakt, levert een syntaxisfout op, met de regel en kolom waar het inlezen stopte. Eerst omzetten, dan valideren.

Wanneer je JSONC of JSON5 beter niet gebruikt

API-payloads en gegevensuitwisseling. RFC 8259 stelt dat een JSON-generator “MUST strictly conform to the JSON grammar” (zich strikt aan de JSON-grammatica moet houden). Aan de ontvangende kant zit meestal JSON.parse of json.loads, en die weigeren allebei commentaar.
package.json. npm vereist strikte JSON. Eén commentaarregel is genoeg om npm-commando’s zoals npm run te laten mislukken met EJSONPARSE.
Bestanden die worden ingelezen door tools die je niet zelf beheert. require('./tsconfig.json') in Node gebruikt de strikte JSON-parser en loopt vast op een tsconfig met commentaar (SyntaxError: …tsconfig.json: Expected property name or '}' in JSON at position 4). Elk script dat een JSONC-bestand inleest, heeft een JSONC-parser nodig.
Een .json-bestand dat ongemerkt JSONC is geworden. De documentatie van Renovate raadt een .jsonc-bestand aan in plaats van een .json-bestand met commentaar, omdat dat laatste “can cause issues with editors and syntax highlighting” (problemen kan geven met editors en syntaxiskleuring). Een expliciete extensie vertelt elke tool wat hij kan verwachten.

Kies je vanaf nul een configuratieformaat en wil je overal commentaar kunnen schrijven, dan hebben TOML en YAML dat ingebouwd. Zie TOML vs JSON vs YAML.

Veelgebruikte configuratiebestanden in de praktijk

JSON5 en JSONC worden al volop gebruikt in configuratiebestanden die je dagelijks tegenkomt. Hier zijn concrete voorbeelden:

TypeScript (tsconfig.json — JSONC)

{
  // Strict mode catches more bugs at compile time
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    // Path aliases for cleaner imports
    "paths": {
      "@/*": ["./src/*"],
      "@tests/*": ["./tests/*"],
    },
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
}

tsconfig.json van TypeScript gebruikt ingebouwde JSONC-ondersteuning — commentaar en afsluitende komma’s werken direct. Dit is een van de meest voorkomende JSONC-bestanden in elk JavaScript/TypeScript-project.

Babel (babel.config.json — JSON5)

Babel leest babel.config.json en .babelrc.json in als JSON5, dus sleutels zonder aanhalingstekens en enkele aanhalingstekens werken daar gewoon.

{
  // Single quotes and unquoted keys make it more readable
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false,  // Let bundler handle modules
    }],
  ],
  plugins: [
    '@babel/plugin-transform-runtime',
  ],
}

VS Code-werkruimte-instellingen (.vscode/settings.json — JSONC)

{
  // Editor preferences
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  // Language-specific overrides
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
}

Praktische tips en aandachtspunten

1. Zet altijd om naar strikte JSON voor productie

Browsers vereisen nog steeds strikte JSON voor JSON.parse. Zet je bestanden daarom tijdens de build om, zoals hierboven beschreven bij het omzetten naar standaard JSON.

2. Veiligheid en betrouwbaarheid

Toegeeflijkheid kan verborgen velden maskeren. Valideer configuraties altijd met JSON Schema of zod voordat je ze verwerkt:

// Validate config shape with zod after parsing
import { readFileSync } from 'node:fs';
import { z } from 'zod';
import JSON5 from 'json5';

const ConfigSchema = z.object({
  port: z.number().min(1).max(65535),
  host: z.string(),
  debug: z.boolean().default(false),
});

const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Gooit een fout als de data ongeldig is

3. Teamafspraken

Vermeld in de README dat *.json5 alleen voor configuraties geldt; releasepakketten moeten strikte .json bevatten.
Standaardiseer Prettier-regels om ruis in diffs te voorkomen.
Gebruik .editorconfig om consistente inspringing af te dwingen voor JSON-, JSON5- en JSONC-bestanden.

4. Prestaties

JSON5/JSONC verwerken voegt afhankelijkheden en een kleine overhead toe — prima voor CLI- en ontwikkeltools, maar meet dit voor productie. Voor configuratiebestanden die eenmalig bij opstarten worden geladen, is dit verwaarloosbaar. Voor veelgebruikte codepaden die duizenden objecten per seconde verwerken, kun je beter bij strikte JSON blijven.

Veelgestelde vragen

Wat is het verschil tussen JSON5 en JSONC?

JSON5 breidt JSON uit met syntax uit ES5.1: sleutels zonder aanhalingstekens, enkele aanhalingstekens, hexadecimale getallen, Infinity/NaN, afsluitende komma’s, regel- en blokcommentaar en meerregelige strings. JSONC is eenvoudiger — het voegt regelcommentaar (//) en blokcommentaar (/* */) toe aan standaard JSON; of afsluitende komma’s ook mogen, hangt af van de parser. Een geldig JSONC-bestand is meestal ook een geldig JSON5-bestand, maar andersom niet. Kies JSONC voor configuratiebestanden waar commentaar voldoende is; kies JSON5 wanneer je rijkere syntax nodig hebt.

Kan ik JSON5 of JSONC gebruiken in productie-API’s?

Nee — JSON5 en JSONC zijn bedoeld voor configuratiebestanden, niet voor gegevensuitwisseling. API’s moeten standaard JSON (RFC 8259) gebruiken voor maximale interoperabiliteit. Reserveer JSON5/JSONC voor lokale configuratiebestanden zoals tsconfig.json, .vscode/settings.json of omgevingsconfiguratie, waar leesbaarheid voor mensen zwaarder weegt dan machineverwerking.

Ondersteunt VS Code JSON5 native?

Niet standaard. De ingebouwde JSON-extensie van VS Code registreert talen zoals json, jsonc en jsonl, maar geen json5. Voor syntaxiskleuring van .json5-bestanden heb je dus een extensie uit de VS Code-marktplaats nodig. JSONC is wel ingebouwd: instellingen, tasks.json, launch.json en tsconfig.json openen allemaal in de modus JSON with Comments.

Hoe zet ik JSON5 om naar standaard JSON?

Gebruik het json5 npm-pakket: JSON5.parse() leest JSON5 in, daarna geeft JSON.stringify() standaard JSON terug. Voor gebruik via de commandoregel voer je npx json5 < input.json5 > output.json uit. Commentaar gaat bij het omzetten verloren, en JSON.stringify maakt van Infinity en NaN gewoon null. Online tools zoals onze JSON Formatter kunnen de omgezette output ook valideren om de juistheid te controleren.

Is JSONC hetzelfde als JSON with Comments?

Ja — “JSON with Comments” is de naam van de taalmodus in VS Code, en jsonc is de bijbehorende taal-ID en bestandsextensie. JSONC wordt gebruikt door VS Code, TypeScript (tsconfig.json) en andere Microsoft-tools. Het volgt de standaard JSON-specificatie en voegt //- en /* */-commentaar toe; of afsluitende komma’s ook mogen, hangt af van de parser. Een formele standaard is er niet; op jsonc.org staat een communityconcept, gebaseerd op wat jsonc-parser met de standaardopties accepteert. Parsers verwijderen commentaar voordat ze de data verwerken, waardoor de resulterende gegevensstructuur identiek is aan standaard JSON.

Probeer onze JSON Formatter om de omgezette JSON direct in de browser te verfraaien en valideren — zonder dat je gegevens je apparaat verlaten.

Conclusie

Leesbaarheid en striktheid in balans brengen is een klassieke ontwikkelaarsuitdaging. JSON5 en JSONC verbeteren de schrijfervaring, en met de juiste build- en validatiepipeline geniet je veilig van de voordelen van “toegeeflijke JSON”.