Kommentare in JSON: JSONC und JSON5 erklärt

Kurze Antwort: Nein. Standard-JSON kennt keine Kommentare, weder // … noch /* … */ noch # …. Ein Kommentar macht das JSON ungültig:

{
  // Port des Servers
  "port": 8080
}

Trotzdem siehst du Kommentare in Dateien wie tsconfig.json oder den Einstellungen von VS Code. Diese Dateien sind streng genommen kein JSON, sondern eine Variante davon. Dieser Ratgeber erklärt die Unterschiede und welche Lösung wann passt.

So lauten die Fehlermeldungen

Umgebung	Meldung
Chrome, Edge, Node.js	`Expected property name or '}' in JSON at position 4` (wie im Beispiel oben) oder `Unexpected token '/', "// …" is not valid JSON` (Kommentar ganz am Anfang)
Firefox	`JSON.parse: expected property name or '}'` oder `JSON.parse: unexpected character`
Safari	`JSON Parse error: Unrecognized token '/'`
Python (`json.loads`)	`Expecting property name enclosed in double quotes` oder `Expecting value`

Die Meldungen nennen das Wort „Kommentar“ nicht. Zeigt die gemeldete Position auf ein /, ist aber fast immer ein Kommentar die Ursache. Der JSON-Formatierer sagt es direkt: „Kommentare sind in JSON nicht erlaubt“.

Warum JSON keine Kommentare hat

JSON wurde als einfaches Austauschformat zwischen Programmen entworfen, nicht als Konfigurationssprache. Douglas Crockford, der JSON bekannt gemacht hat, hat nach eigener Aussage Kommentare bewusst herausgenommen: Er hatte gesehen, dass manche sie für Anweisungen an den Parser nutzten. Das hätte die Austauschbarkeit zerstört – ein Programm hätte dieselbe Datei anders verstanden als ein anderes.

Die Folge: Jeder JSON-Parser auf der Welt liest dieselben Daten gleich. Der Preis: Für Dateien, die Menschen schreiben und lesen, fehlt etwas.

Möglichkeit 1: ein Kommentarfeld

Die einfachste Lösung, die mit jedem Parser funktioniert, ist ein normales Feld:

{
  "_kommentar": "Port des Servers; 8080 nur für die Entwicklung",
  "port": 8080
}

Das bleibt gültiges JSON. Der Nachteil: Der „Kommentar“ ist ein Datenfeld. Das Programm liest ihn mit ein, und ein Schema, das unbekannte Felder verbietet, lehnt ihn ab. Für Konfigurationen, die du selbst einliest, ist das oft trotzdem die pragmatischste Lösung.

Möglichkeit 2: JSONC

JSONC steht für „JSON with Comments“: JSON, das zusätzlich //- und /* */-Kommentare erlaubt. VS Code verwendet es für settings.json und andere Einstellungsdateien, und auch TypeScript liest tsconfig.json mit Kommentaren.

Wichtig: JSONC ist kein offizieller Standard, sondern eine Konvention. Ob Kommas am Ende zusätzlich erlaubt sind, hängt vom jeweiligen Programm ab. Und: Ein normaler JSON-Parser wie JSON.parse() liest JSONC nicht. Wer solche Dateien selbst einlesen will, braucht einen passenden Parser oder muss die Kommentare vorher entfernen.

Möglichkeit 3: JSON5

JSON5 geht weiter und erlaubt vieles, was aus JavaScript bekannt ist:

// JSON5
{
  // Kommentare
  name: 'Ada',            // Schlüssel ohne Anführungszeichen, einfache Anführungszeichen
  sprachen: ['de', 'en',], // Komma am Ende
  maske: 0xFF,            // Hexadezimalzahlen
}

JSON5 hat eine eigene Spezifikation und Parser für viele Sprachen. Es eignet sich gut für Dateien, die Menschen schreiben. Für den Austausch zwischen Programmen ist es weniger geeignet, weil nicht jedes Programm JSON5 liest.

Möglichkeit 4: YAML

Wenn du eine Konfigurationsdatei neu anlegst und Kommentare brauchst, ist YAML oft die bessere Wahl. YAML erlaubt Kommentare mit # und braucht weder Klammern noch Kommas:

# Port des Servers
port: 8080
sprachen:
  - de
  - en

Jedes gültige JSON lässt sich in YAML umwandeln, zum Beispiel mit dem Tool JSON in YAML umwandeln. Enthält dein JSON schon Kommentare, entferne sie vorher, denn der Konverter erwartet gültiges JSON – und schreibe sie danach als #-Kommentare ins YAML.

Was passt wann?

	JSON	JSONC	JSON5	YAML
Kommentare	nein	ja	ja	ja (`#`)
Komma am Ende	nein	je nach Programm	ja	nicht nötig
Einfache Anführungszeichen	nein	nein	ja	ja
Schlüssel ohne Anführungszeichen	nein	nein	ja	ja
Liest `JSON.parse()`	ja	nein	nein	nein

Die Faustregel:

Daten zwischen Programmen (APIs, Exporte, Nachrichten): Standard-JSON, ohne Kommentare.
Konfiguration für ein Werkzeug, das JSONC oder JSON5 erwartet: Halte dich an das, was das Werkzeug dokumentiert.
Eigene, neue Konfigurationsdateien mit Erklärungen: YAML oder JSON5.

Kommentare aus einer Datei entfernen

Musst du eine Datei mit Kommentaren an ein Programm geben, das nur JSON liest, entferne die Kommentare vorher. Für einzelne Dateien geht das von Hand. Automatisch geht es am sichersten mit einem Parser, der das Format versteht – etwa einer JSON5-Bibliothek –, der die Daten einliest und als Standard-JSON wieder ausgibt.

Von einem einfachen Suchen-und-Ersetzen nach // ist abzuraten: In Texten wie "url": "https://example.com" steht // auch ohne Kommentar.