JSON Grundlagen: Aufbau, häufige Fehler und wie Sie sie finden

JSON (JavaScript Object Notation) ist ein textbasiertes Format, um strukturierte Daten zu speichern und zwischen Programmen auszutauschen. Ursprünglich aus JavaScript abgeleitet, ist es heute sprachunabhängig und in RFC 8259 standardisiert. Ob Wetter-API, Online-Shop, Smart-Home-Gerät oder die package.json eines Webprojekts: Überall stecken JSON-Daten dahinter. Das Format ist für Menschen gut lesbar, aber für Maschinen gnadenlos – ein einziges falsches Komma macht die ganze Datei ungültig.

Aufbau und Datentypen

Ein JSON-Dokument besteht aus genau einem Wert. Meist ist das ein Objekt (geschweifte Klammern) oder ein Array (eckige Klammern).

{
  "kunde": "Müller GmbH",
  "kundennummer": 10482,
  "aktiv": true,
  "rabatt": 0.05,
  "ansprechpartner": null,
  "adresse": {
    "strasse": "Hauptstraße 12",
    "plz": "80331",
    "ort": "München"
  },
  "tags": ["B2B", "Bayern"]
}

Achtung bei deutschen Zahlen: 0,05 ist kein gültiger JSON-Wert. Dezimalzahlen werden immer mit Punkt geschrieben. Postleitzahlen speichern Sie besser als String ("01067"), sonst geht die führende Null verloren.

Die Syntaxregeln im Überblick

1. Schlüssel stehen immer in doppelten Anführungszeichen.
2. Strings ebenfalls in doppelten Anführungszeichen, nie in einfachen.
3. Elemente werden durch Kommas getrennt, nach dem letzten Element kein Komma.
4. Keine Kommentare.
5. Sonderzeichen in Strings werden mit Backslash maskiert: \", \\, \n, \t, \u00fc.
6. Die Datei sollte in UTF-8 kodiert sein; Umlaute dürfen direkt im Text stehen.
7. Keine Werte wie undefined, NaN oder Infinity.

Die häufigsten Fehler

Komma am Ende (Trailing Comma):

{
  "name": "Anna",
  "alter": 34,
}

Das Komma nach 34 ist ungültig. In JavaScript-Code ist es erlaubt, in JSON nicht.

Einfache Anführungszeichen oder fehlende Anführungszeichen:

{ 'name': 'Anna' }      ← ungültig
{ name: "Anna" }        ← ungültig
{ "name": "Anna" }      ← korrekt

Typografische Anführungszeichen: Wer JSON aus Word, Outlook oder einem Chat kopiert, bekommt oft „“ statt “. Der Parser erkennt diese Zeichen nicht.

Zeilenumbruch im String: Ein echter Umbruch innerhalb von Anführungszeichen ist verboten; schreiben Sie \n.

Windows-Pfade: "C:\Users\anna" ist ungültig, weil \U und \a als Escape-Sequenzen gelesen werden. Richtig: "C:\\Users\\anna".

Mehrere Wurzelelemente: Zwei Objekte hintereinander ohne umschließendes Array sind kein gültiges JSON (Ausnahme: das Format JSON Lines, das pro Zeile ein Objekt erwartet).

BOM am Dateianfang: Manche Editoren unter Windows speichern ein unsichtbares Byte-Order-Mark, das einige Parser ablehnen.

Fehlermeldungen richtig lesen

Typische Meldungen und ihre Bedeutung:

Die Positionsangabe zählt Zeichen ab Dateianfang. Ein Formatter zeigt stattdessen Zeile und Spalte – das ist deutlich bequemer. Mit dem JSON-Formatter fügen Sie Daten ein, sehen sie eingerückt und erhalten bei Fehlern den genauen Ort.

Formatieren, minifizieren, validieren

• Formatieren (Pretty Print): Einrückung mit zwei oder vier Leerzeichen macht verschachtelte Strukturen lesbar.
• Minifizieren: Entfernt alle überflüssigen Leerzeichen und Umbrüche, um Übertragungsgröße zu sparen.
• Validieren: Prüft die Syntax. Ob die Inhalte stimmen (z. B. ob plz fünfstellig ist), prüft ein JSON Schema, das Datentypen, Pflichtfelder und Muster festlegt.

Auf der Kommandozeile hilft das Werkzeug jq:

jq . daten.json          # formatieren und prüfen
jq '.adresse.ort' daten.json   # einzelnes Feld auslesen

Für Felder mit festen Mustern, etwa Postleitzahlen oder E-Mail-Adressen, kommen in Schemas reguläre Ausdrücke zum Einsatz; mehr dazu im Ratgeber Regex Grundlagen.

JSON oder CSV?

Eine Besonderheit im deutschsprachigen Raum: Excel speichert CSV oft mit Semikolon als Trennzeichen und Komma als Dezimaltrenner. Beim Umwandeln nach JSON muss das berücksichtigt werden, sonst landen ganze Zeilen in einem Feld. Mit CSV zu JSON wandeln Sie Tabellen in beide Richtungen um.

Sicherheit und gute Praxis

• Nie mit eval() parsen, sondern immer mit JSON.parse() oder der Bibliothek Ihrer Sprache.
• Keine Geheimnisse wie API-Schlüssel in öffentlich ausgelieferte JSON-Dateien schreiben.
• Große Zahlen: JavaScript kann Ganzzahlen nur bis 2^53 − 1 exakt darstellen. IDs von Datenbanken oder Social-Media-Plattformen daher als String übertragen.
• Datumsangaben als ISO-8601-String ("2026-10-07T09:30:00Z") oder als Unix-Timestamp speichern; mehr im Ratgeber Unix-Timestamp erklärt.

JSON in Konfigurationsdateien

Viele Werkzeuge speichern ihre Einstellungen als JSON, etwa package.json (Node.js), tsconfig.json, composer.json (PHP) oder das Web-App-Manifest. Ein Fehler darin führt oft zu kryptischen Meldungen beim Start. Drei Tipps:

1. Editor mit Syntaxprüfung nutzen: VS Code markiert Fehler sofort rot und kennt für bekannte Dateien sogar das Schema mit allen erlaubten Feldern.
2. Kommentare vermeiden: Manche Dateien wie tsconfig.json akzeptieren Kommentare (JSONC), andere wie package.json nicht. Im Zweifel ein Feld wie "_hinweis": "..." verwenden.
3. Versionierung: Konfigurationsdateien in Git einchecken. So lässt sich nachvollziehen, welche Änderung einen Fehler verursacht hat.

Checkliste

• Doppelte Anführungszeichen für Schlüssel und Strings.
• Kein Komma nach dem letzten Element, keine Kommentare.
• Dezimalpunkt statt Komma, PLZ als String.
• UTF-8 ohne BOM speichern.
• Mit Formatter prüfen, bei Bedarf JSON Schema für Inhalte.