Was ist eine JSON-Datei?

JSON ist ein reines Textformat, das sich in jedem Editor öffnen lässt. Eingesetzt wird es für den Austausch zwischen Programmen und das Web.

Die Endung lautet .json, der volle Name JavaScript Object Notation. Beides sagt weniger aus als das, was die Datei halten kann — und davon handelt der Rest dieser Seite.

Es geht auf 2001 zurück. Die Spezifikation ist RFC 8259.

Das Alter ist aus einem praktischen Grund interessant: je älter ein Format, desto mehr Programme hatten Zeit, es zu lernen.

Sie ist vollständig veröffentlicht, das Format lässt sich also aus dem Dokument umsetzen statt durch Nachsehen. Deshalb taucht es in so vielen Programmen auf, und deshalb gehen Dateien von vor zwanzig Jahren heute noch auf. Veröffentlicht heißt allerdings nicht lizenzfrei: Wo ein Format einen Codec einpackt, ist die Patentfrage eine eigene, die der Standard nicht mitbeantwortet.

JSON speichert seinen Inhalt exakt. Erneutes Speichern ändert nichts, es lässt sich also beliebig oft öffnen, bearbeiten und wieder ablegen, ohne dass sich Schaden ansammelt — genau das macht es zu einem Arbeitsformat und nicht zu einem Ausgabeformat.

JSON hat keine Kommentarsyntax. Alles Erklärende muss außerhalb der Datei leben — gut zu wissen, bevor man sie für etwas wählt, das ein Mensch von Hand pflegt.

Visual Studio Code, jq und Postman lesen es, und die meisten Programme derselben Art ebenfalls.

Wenn eine Datei nicht aufgeht, liegt es selten am Format — häufiger daran, dass das Programm älter ist als das Format. Die Umwandlung in etwas Älteres ist der verlässliche Weg daran vorbei, und dafür gibt es den Rest dieser Website.

Jeder aktuelle Browser liest es.

Damit lässt es sich bedenkenlos auf eine Seite stellen oder an eine Nachricht hängen, ohne sich zu fragen, was die Gegenseite installiert hat.

JSON ist zum Öffnen und Ändern gedacht. Behalte die Datei in diesem Format, solange die Arbeit läuft, und exportiere daraus, wann immer eine fertige Fassung gebraucht wird.

Ein JSON-Dokument besteht aus Objekten, Feldern, Zeichenketten, Zahlen, Wahrheitswerten und null. Das ist der gesamte Wortschatz, und genau seine Kürze ist der Grund, warum sich das Format durchgesetzt hat: Jede Programmiersprache kennt alle sechs bereits, sodass ein Dokument zu lesen bedeutet, eine einzige Funktion aufzurufen und native Werte zurückzubekommen, ohne dass irgendetwas übersetzt werden müsste.

Die Spezifikation passt auf ein paar Seiten. Sie wurde eher beschrieben als entworfen — Douglas Crockford schrieb auf, was die Objektschreibweise in JavaScript ohnehin schon konnte —, weshalb sie sich naheliegend anfühlt statt raffiniert.

JSON hat absichtlich keine Kommentare, und das ist die meistkritisierte Eigenschaft des Formats. Die Begründung war, dass Kommentare zu eigenen Verarbeitungsanweisungen einladen — die Folge ist, dass sich JSON als Konfigurationssprache schlecht eignet, so gut es auch als reines Austauschformat funktioniert.

Drei Notlösungen sind im Umlauf. Ein Feld mit einem Namen wie Unterstrich-Kommentar, das jeder Parser akzeptiert und jeder Schema-Validator ablehnt. JSON5 und JSONC, die Kommentare und abschließende Kommas erlauben und damit kein echtes JSON mehr sind — die Einstellungsdatei von Visual Studio Code ist JSONC, weshalb sie in einem strengen JSON-Werkzeug sofort einen Fehler wirft. Und die ehrliche Antwort: Für alles, was ein Mensch dauerhaft pflegt, sind TOML oder YAML die passendere Wahl.

JSON unterscheidet nicht zwischen Ganzzahl und Kommazahl. Die meisten Parser lesen jede Zahl als Fließkommazahl doppelter Genauigkeit, und die hält Ganzzahlen nur bis etwa neun Billiarden exakt.

Danach ändern sich Werte still, ohne Fehlermeldung — eine 64-Bit-Kennung, eine hohe Rechnungs- oder Kundennummer, ein Betrag in der kleinsten Einheit, alles kann als eine andere Zahl zurückkommen als die gesendete. Die Abhilfe ist, solche Werte als Zeichenkette zu übertragen, was jede ernsthafte Schnittstelle tut, und es lohnt sich, das bei der Anbindung an eine Behörden- oder Buchhaltungsschnittstelle nachzuprüfen statt vorauszusetzen.

Doppelte Schlüssel sind nicht verboten. Parser gehen unterschiedlich damit um — die meisten behalten den letzten, manche den ersten, wenige melden einen Fehler —, und ein Dokument, das sich auf das eine oder das andere verlässt, verlässt sich auf eine bestimmte Implementierung, nicht auf JSON selbst.

Die Reihenfolge der Schlüssel ist ebenfalls nicht garantiert erhalten, weshalb es ein Fehler ist, ein Objekt als geordnete Struktur zu behandeln — kommt es auf die Reihenfolge an, gehört ein Feld verwendet. Und es gibt keine Datumsangaben: Die verbreitete Konvention ist eine ISO-8601-Zeichenkette, und jeder Parser liefert lediglich Text, den der eigene Code interpretieren muss.

JSON ist UTF-8. Die Spezifikation verlangt das für alles, was zwischen Systemen ausgetauscht wird, und die praktische Folge ist, dass eine Byte-Order-Mark nicht erlaubt ist — jene drei unsichtbaren Bytes am Dateianfang, die einen Parsing-Fehler auslösen, dessen Meldung meist das erste Zeichen beschuldigt statt die eigentliche Ursache zu nennen. Windows-Notepad schrieb bis vor wenigen Jahren standardmäßig genau diese Bytes, und wer eine JSON-Datei mit Umlauten dort speichert und einfügt, trägt das Problem unwissentlich mit weiter.

Eine zweite Falle ist rein deutsch: Wer aus Gewohnheit ein Komma statt eines Punktes bei einer Zahl schreibt — 3,14 statt 3.14 —, weil im Deutschen jede Dezimalzahl mit Komma geschrieben wird, bekommt einen Syntaxfehler an genau dieser Stelle. JSON kennt nur den Punkt, und wer Testdaten von Hand tippt, tut gut daran, diese eine Stelle bewusst zu prüfen.

Ein JSON-Dokument muss vollständig sein, bevor es sich lesen lässt — erst die schließende Klammer macht es gültig —, sodass ein zehn Gigabyte großes Feld voller Datensätze komplett in den Speicher geladen werden muss, bevor der erste Eintrag verfügbar ist. Für große Exporte und Protokoll-Pipelines ist das schlicht nicht praktikabel.

NDJSON, auch JSON Lines genannt, löst das, indem jede Zeile ein vollständiges JSON-Objekt trägt, ohne umschließendes Feld. Jede Zeile lässt sich unabhängig lesen, sodass eine Datei beliebiger Größe zeilenweise verarbeitet werden kann und ein Prozess sofort mit dem ersten Datensatz arbeiten kann. Datenexporte, Protokollversand und Trainingsdaten für maschinelles Lernen setzen fast durchweg darauf, und es ist das Format der Wahl, sobald eine JSON-Datei in Gigabyte gemessen wird.

JSON Schema ist der Standardweg, um zu beschreiben, wie ein gültiges Dokument aussieht, und lohnt sich für jede Schnittstelle zwischen zwei Systemen — es macht aus „die Schnittstelle liefert etwas Merkwürdiges" einen konkreten Fehler mit Feldname. Die Unterstützung ist gut, wenn auch weniger einheitlich als beim vergleichbaren Mechanismus für XML.

Für die alltägliche Arbeit reicht ein Editor mit JSON-Unterstützung meist völlig aus: Ein fehlendes oder überzähliges Komma wird direkt markiert, und maschinell erzeugtes JSON, das als eine einzige lange Zeile ankommt, lässt sich mit einem Klick lesbar formatieren. Beides sind Zwei-Sekunden-Handgriffe, die überraschend viel Zeit sparen.