YAML in NDJSON umwandeln

In vielen deutschen Fertigungsbetrieben laufen die Sensoren und Steuerungen einer Anlage auf eigener Hardware statt in der Cloud eines amerikanischen Anbieters, allein schon, weil Produktionsdaten den Werksstandort nicht ohne Weiteres verlassen sollen. Ein Export aus der Anlagensteuerung liegt dabei häufig als YAML vor, während das dahinterliegende, selbst betriebene Log- oder Zeitreihensystem NDJSON erwartet — eine Zeile pro Messung.

Diese Umwandlung überbrückt genau das: Sie liest die YAML-Datei und schreibt eine Zeile pro Datensatz. Wie genau sie dabei entscheidet, wo ein Datensatz endet, ist die einzige Regel, die man kennen muss, um das Ergebnis vorherzusagen.

NDJSON ist JSON mit einer Regel für Zeilenumbrüche: ein vollständiger Wert pro Zeile, keine Kommas, keine umschließenden Klammern. Damit das entsteht, muss irgendetwas entscheiden, wo ein Datensatz endet und der nächste beginnt, und das Einzige in einer YAML-Datei, das das ausdrückt, ist eine Sequenz auf oberster Ebene. Ein Dokument, das mit einer Liste aus Bindestrichen beginnt, wird zu einer Zeile pro Eintrag.

Alles andere wird eine einzige Zeile. Eine Zuordnung auf oberster Ebene ist ein einziger Wert, egal wie viel darunter verschachtelt ist — ein Export mit einem Anlagenkopf, gefolgt von den eigentlichen Messwerten, kommt als eine mehrere Kilobyte lange Zeile heraus. Das ist kein Fehler, aber selten das, was jemand wollte, weshalb es hier zuerst steht statt in einer Fußnote.

Stecken die Datensätze unter einem Schlüssel — eine messungen-Liste innerhalb eines größeren Exports —, greift die Umwandlung nicht hinein, um sie zu finden. Sie sieht nur die oberste Ebene. Die Lösung ist, diese Liste vor der Umwandlung an die Spitze des Dokuments zu heben, was im Editor bedeutet, die erste Zeile zu löschen und den Rest auszurücken.

Der andere Weg ist, zuerst nach JSON umzuwandeln und mit jq zu selektieren und zu streamen — ein einziger Ausdruck, der das Array herauszieht und Element für Element ausgibt. Das lohnt sich, wenn dieselbe Extraktion wiederholt wird, weil sie sich skripten lässt; diese Seite lohnt sich, wenn es einmalig passiert.

YAML-Anker lassen einen Block einmal definieren und mehrfach referenzieren, und der Parser löst jeden Alias vor dem Schreiben zu einer vollständigen Kopie auf. Das NDJSON ist deshalb größer als die YAML, mitunter deutlich.

Für einen Strom ist das kein Kostenfaktor, sondern die Voraussetzung. Ein Werkzeug, das NDJSON liest, verarbeitet eine Zeile nach der anderen und hat die anderen unter Umständen nie gesehen — genau darauf beruht das Format, und genau das erlaubt es, eine Datei auf mehrere Worker zu verteilen oder nach einem Abbruch fortzusetzen. Eine Zeile, die sich auf eine frühere Definition verlassen hätte, würde unter genau den Bedingungen scheitern, für die das Format gebaut ist.

Ein YAML-Strom mit --- Trennzeichen ist im Kern schon NDJSON: ein Dokument pro Datensatz, in Reihenfolge. Das ist die strukturell nächste Entsprechung in dieser ganzen Formatfamilie — und ausgerechnet die eine Eingabe, die diese Umwandlung ablehnt, weil der Parser genau ein Dokument liest und beim zweiten stoppt.

Der Ausweg ist eine Textbearbeitung statt eines Werkzeugs: jedes --- durch eine Listenmarkierung ersetzen und die Dokumente darunter einrücken, dann wandelt die Datei genau in den erwarteten Strom um. Bei einer großen Datei erledigt das ein sed-Aufruf, bei ein paar Dokumenten der Editor.

NDJSON ist seit rund 2013 das Austauschformat für zeilenorientierte Werkzeuge, und die Ziele wollen leicht unterschiedliche Dinge. Ein Zeitreihensystem oder ein Loader mit fester Zeile-für-Datensatz-Logik nimmt diese Ausgabe unverändert.

Ein selbst betriebenes Elasticsearch oder OpenSearch ist die Stelle, an der man stolpert. Dessen Bulk-API ist NDJSON-förmig, erwartet aber eine Aktionszeile vor jedem Dokument, sodass eine Datei aus reinen Datensätzen abgelehnt wird. Diese Aktionszeilen einzufügen ist bewusst nicht Teil dieser Umwandlung, denn sie benennt einen Index und eine Operation, die nur die Betreiberin der Anlage kennt.

Jede Zeile ist kompaktes JSON, ohne Einrückung, in der Schlüsselreihenfolge der YAML. Die Typen stammen vom YAML-Parser: Ein unquotiertes Datum bleibt unter YAML 1.2 eine Zeichenkette, sodass ein Zeitstempelfeld als reiner Text ankommt statt als etwas, das ein Loader ohne Schema-Hinweis als Zeit erkennt.

Große Ganzzahlen sind das stille Risiko. Eine Seriennummer wie 9223372036854775807 kommt als 9223372036854776000 heraus, weil JSON-Zahlen IEEE-Doubles sind. Wer solche IDs in der YAML als Zeichenkette in Anführungszeichen setzt, bekommt sie unverändert zurück — genau das, was eine Kennung ohnehin hätte sein sollen.

Eine Liste, deren Einträge nicht dieselben Schlüssel teilen, wandelt sich ohne Beschwerde um, und jede Zeile trägt nur die Schlüssel, die ihr Datensatz hatte. Das ist ein echter Vorteil gegenüber einer Umwandlung derselben Daten nach CSV, wo die Spalten die Vereinigung aller Datensätze bilden müssen und fehlende Felder aufgefüllt werden.

Ob das Zielsystem das genauso gelassen nimmt, ist eine andere Frage. Ein schema-freies System verarbeitet unregelmäßige Zeilen anstandslos, ein Loader mit festem Schema weist unerwartete Felder zurück oder setzt sie auf null. Die Umwandlung gibt wieder, was die YAML sagte — die ersten und letzten Zeilen einer großen Ausgabe kurz anzusehen zeigt, wie stark die Form über die Datei hinweg schwankt.

Ist die YAML-Datei eine Konfiguration statt Daten, hat diese Umwandlung nichts zu bieten. Eine einzige minifizierte JSON-Zeile ist in jeder Hinsicht schlechter zu lesen als die YAML, und kein Stream-Verbraucher wollte eine Konfigurationsdatei.

Der Umweg lohnt sich, wenn die Datei tatsächlich eine Liste ist — exportierte Messreihen, Testdaten, ein von Hand geschriebenes Ereignisprotokoll —, und das Ziel Zeilen liest. In diesem Fall ist die Umwandlung sofort fertig, läuft vollständig im Browser, und übrig bleibt nur, die erste und die letzte Zeile zu prüfen.

Parsen und Schreiben laufen beide als JavaScript in diesem Tab. Eine Messreihe mit internen Anlagenbezeichnungen oder Standortdaten verlässt das eigene Netz nicht, und Dateien bis 100 MB werden auf der kostenlosen Stufe angenommen.

Für einen Betrieb, der genau deshalb auf eigene Server statt auf einen Cloud-Dienst setzt, ist das kein Nebeneffekt, sondern der Punkt der Sache: Es gibt hier nichts hochzuladen und nichts, das ein fremder Server je zu sehen bekommt.