JSON Lines: ein Wert pro Zeile für Logs, Datensätze und gestreamte Antworten

Worum es geht

Die zitierte JSON-Lines-Seite nennt drei Anforderungen: UTF-8-Kodierung ohne Byte Order Mark; jede Zeile ist ein gültiger JSON-Wert, sodass eine leere Zeile ein Fehler ist; und das Zeilenendezeichen ist \n (CRLF wird toleriert, weil umgebende Leerzeichen beim Parsen eines Werts ignoriert werden). Ein Abschlusszeichen nach dem letzten Wert wird empfohlen, damit sich Dateien sauber aneinanderhängen lassen. Übliche Konventionen sind die Dateiendung .jsonl, gzip oder bzip2 zur Komprimierung sowie ein noch nicht standardisierter Medientyp application/jsonl. Das verwandte IETF-Format JSON Text Sequences (RFC 7464, zitiert) stellt das ASCII-Record-Separator-Byte (0x1E) vor jeden Text und registriert application/json-seq; seine Parsing-Regeln sind so geschrieben, dass ein abgeschnittenes Element übersprungen und der Rest der Sequenz wiederhergestellt werden kann, und es hat kein Sequenzende-Zeichen.

Warum es wichtig ist

Ein JSON-Array ist ein einziger Wert: Die lesende Seite muss entweder den gesamten Text vorhalten oder einen inkrementellen Parser verwenden, und ein abgeschnittenes Array ist schlicht ungültig. Mit einem Wert pro Zeile wird jeder Datensatz für sich geparst, sodass eine schreibende Seite anhängen kann, ohne die Datei neu zu schreiben, ein Absturz höchstens die letzte Zeile kostet, sich eine grosse Datei zeilenweise für parallele Verarbeitung aufteilen lässt und Shell-Werkzeuge (grep, head, wc -l, jq -c) direkt funktionieren. Dieselbe Eigenschaft macht das Format für gestreamte HTTP-Antworten und für Nachrichten zwischen Prozessen geeignet.

So wird es angewendet

• Datensätze kompakt serialisieren, nie mit Einrückung: JSON escapt Steuerzeichen innerhalb von Strings, sodass ein kompakter Wert keinen rohen Zeilenumbruch enthält.
• Jeder Zeile dieselbe Form geben (ein Objekt mit stabilen Schlüsseln) und die Form im Dateinamen oder in einem einleitenden Kopf-Datensatz versionieren, wenn sie sich ändern muss.
• Bei einer gestreamten Antwort nach jeder Zeile flushen und einen Fehlschlag in eine abschliessende Zeile mit einem expliziten "error"-Feld legen; die Client-Seite kann sich nicht auf eine schliessende Klammer verlassen, um zu wissen, dass der Stream sauber endete, daher bei Bedarf an Vollständigkeit einen expliziten Abschlussdatensatz hinzufügen.
• application/json-seq wählen, wenn die konsumierende Seite sich von einer Beschädigung mitten im Stream erholen muss; JSON Lines wählen, wenn Kompatibilität mit Textwerkzeugen wichtiger ist.
• Ganze Dateien mit einem Stream-Kompressor komprimieren; das Format bleibt nach der Dekomprimierung zeilenadressierbar.

Stolpersteine

Eine einzelne sehr lange Zeile muss trotzdem in den Speicher passen. Werkzeuge, die bei einem einzelnen CR oder bei U+2028 aufteilen, weichen von der Spezifikation ab. Wird "Zeile 1" im Editor und "Wert 1" im Programm gezählt (die Seite schlägt Letzteres vor), entstehen Off-by-one-Fehlerberichte. Die ganze Datei als ein einziges JSON-Dokument zu validieren, scheitert konstruktionsbedingt; zeilenweise validieren und eine letzte unvollständige Zeile als Abschneidung statt als Beschädigung behandeln.