TSV in JSON umwandeln

Wer eine Tabelle aus GENESIS-Online, der Datenbank des Statistischen Bundesamts, oder aus einem Landesamt für Statistik herunterlädt, bekommt oft eine tabgetrennte Datei angeboten, gerade weil Ortsnamen, Berufsbezeichnungen und Kategorien voller Kommas und Punkte stecken, die eine kommagetrennte Datei stören würden.

Für ein Skript oder ein Auswertungstool ist die Datei in dieser Form trotzdem unhandlich: Es gibt keine Typen, keine Verschachtelung, und ein Tabulator innerhalb eines Wertes lässt sich mit den Mitteln der Datei selbst nicht sicher unterscheiden von einem Spaltenumbruch.

Die Kopfzeile liefert die Schlüssel, jede weitere Zeile wird zu einem Objekt. Am Ende steht ein JSON-Array — genau die Form, die ein Skript, ein Notebook oder eine fetch-Abfrage in JavaScript erwartet, wenn von „den Daten" die Rede ist.

Es wird nichts um das Array herum verpackt und keine Spalte automatisch als Schlüssel für ein Lookup-Objekt verwendet, weil das voraussetzen würde zu wissen, welche Spalte die eindeutige Kennung ist — das kann die Umwandlung nicht entscheiden, das muss beim Weiterverarbeiten passieren.

Eine tabgetrennte Datei hat keine anerkannte Möglichkeit, einen Tabulator innerhalb eines Feldes zu kennzeichnen, und ein Zeilenumbruch mitten in einem Wert ist noch problematischer: Die Zeile endet dort, wo der Wert eigentlich weiterlaufen sollte. Beides kommt in der Praxis vor, meist in einer Anmerkungs- oder Beschreibungsspalte.

In JSON sind das gewöhnliche Zeichen: Ein Tabulator wird als \t innerhalb der Zeichenkette geschrieben, ein Zeilenumbruch als \n, und keines von beiden kann die Struktur des Dokuments durcheinanderbringen, weil diese Struktur über geschweifte und eckige Klammern ausgedrückt wird und nicht über die Zeichen in den Daten selbst.

Eine Überschrift wie „Kreis" wird zum Schlüssel „Kreis", eine Überschrift wie „Bevölkerung (in 1.000)" behält ihre Klammern. Nichts wird umbenannt oder in ein Programmierschema übersetzt, weil eine Umwandlung, die eigenmächtig Spaltennamen ändert, das Ergebnis nicht mehr mit der Quelle vergleichbar machen würde.

Das hat Folgen bei der Weiterverarbeitung: `zeile.Bevölkerung (in 1.000)` ist in den meisten Sprachen keine gültige Schreibweise, `zeile["Bevölkerung (in 1.000)"]` schon. Wer die Schlüssel bereinigen will, macht das einmal in der Kopfzeile vor der Umwandlung oder einmal danach im JSON, statt sich mit der Originalschreibweise durch den ganzen Code zu arbeiten.

JSON unterscheidet zwischen 7 und "7", eine tabgetrennte Datei nicht, also wird geraten: Werte, die wie Zahlen aussehen, werden zu JSON-Zahlen, true und false zu Booleans, alles andere bleibt Zeichenkette. Für Einwohnerzahlen oder Prozentwerte ist das genau richtig.

Für einen amtlichen Gemeindeschlüssel ist es das nicht. Eine achtstellige Kennziffer, die mit einer 0 beginnt, wird als Zahl ohne die führende 0 gelesen, und danach lässt sich die ursprüngliche Schreibweise nicht mehr rekonstruieren. Solche Spalten lohnt es sich im Ergebnis zu prüfen, bevor sie irgendwo als Schlüssel dienen.

Eine leere Zelle zwischen zwei Tabulatoren wird als `null` geschrieben. Das ist eine bewusste Entscheidung, denn ein Konsument des JSON behandelt null und "" unterschiedlich — eine Schema-Prüfung, die eine Zeichenkette erwartet, weist null zurück, auch wenn beide in einer einfachen Wahrheitsprüfung als „nichts" durchgehen.

Die Quelltabelle kann nicht sagen, ob eine Zelle bewusst leer gelassen wurde oder ob der Wert schlicht fehlt — eine tabgetrennte Datei hat für beide Fälle nur die eine leere Stelle. Wenn dieser Unterschied wichtig ist, muss er schon in der Ausgangsdatei stehen, etwa als eigene Markierung.

Die Schlüssel kommen aus der Kopfzeile, und jede spätere Zeile wird an ihr gemessen. Taucht in einer Tabellenerweiterung plötzlich eine zusätzliche Spalte auf, ohne dass die Kopfzeile angepasst wurde, bekommt diese Spalte keinen eigenen Schlüssel.

Die überzähligen Werte landen stattdessen gesammelt unter dem Schlüssel `__parsed_extra`, als Array, nur bei den betroffenen Zeilen. Das macht eine unregelmäßige Tabelle sichtbar, statt sie stillschweigend falsch zuzuordnen — ein Blick mit `jq` auf ein paar Zeilen zeigt sofort, ob das Feld vorkommt.

Jede Zeile wiederholt jeden Schlüssel, jede Zeichenkette bekommt Anführungszeichen, dazu kommt die Interpunktion des Objekts. Bei einer breiten Tabelle mit langen Spaltenüberschriften und kurzen Werten kann das JSON ein Vielfaches der Ausgangsdatei ausmachen.

Das ist ein fairer Preis für eine Datei, mit der weitergerechnet wird, und ein schlechter für eine Datei, die nur archiviert werden soll. Die Ausgabe ist zusätzlich mit zwei Leerzeichen eingerückt, was sie im Editor lesbar macht und ebenfalls Bytes kostet — für Speicherung oder einen Datenstrom ist NDJSON die kompaktere Alternative.

`jq "length"` liefert die Zeilenzahl, ohne dass die Kopfzeile mitzählt. `jq ".[0] | keys"` zeigt die Spalten so, wie der Parser sie gelesen hat. `jq "[.[].Bundesland] | unique"` zeigt jeden vorkommenden Wert einer Spalte — nützlich, um herauszufinden, welche Schreibweise eine Statistikbehörde für „keine Angabe" verwendet hat.

Das ist gerade bei amtlichen Tabellen eine schnellere Methode als das Öffnen der Datei in einer Tabellenkalkulation, die auf dem Weg wiederum ihre eigenen, oft unbemerkten Umwandlungen vornimmt — etwa an genau den Gemeindeschlüsseln, die vorher schon Zahlen wurden.

Sowohl das Lesen der tabgetrennten Datei als auch das Schreiben des JSON laufen als gewöhnliches JavaScript auf dieser Seite, es wird also nichts hochgeladen. Das ist bei einer noch unveröffentlichten Auswertung oder einem Datenauszug mit eingeschränkter Weitergabe kein Nebenpunkt.

Das Array wird vollständig im Arbeitsspeicher aufgebaut, bevor es geschrieben wird — mehrere Dutzend Megabyte sind unproblematisch, bei einigen Hundert wird ein Browser-Tab spürbar langsamer. Für eine so große Tabelle ist NDJSON die Form, die diese Grenze nicht kennt, und sie entsteht aus derselben Quelle.