JSON zu CSV umwandeln: die vollständige Anleitung

JSON und CSV sind zwei der am weitesten verbreiteten Textformate für den Datenaustausch. Beide speichern strukturierte Daten als reinen Text, aber sie tun das mit sehr unterschiedlichen Annahmen über die Form der Daten. Die Umwandlung von JSON nach CSV ist deshalb keine reine Syntax-Übersetzung, sondern erzwingt Entscheidungen darüber, wie hierarchische Daten in eine flache Tabelle gepresst werden. Wer diese Entscheidungen versteht, vermeidet Datenverlust und kaputte Importe.

Was JSON ist

JSON (JavaScript Object Notation) ist ein textbasiertes Format zur Darstellung strukturierter Daten. Es kennt eine kleine Menge von Bausteinen: Objekte (Schlüssel-Wert-Paare in geschweiften Klammern), Arrays (geordnete Listen in eckigen Klammern), Strings, Zahlen, Booleans und null. Aus diesen Bausteinen lassen sich beliebig tiefe Hierarchien bauen. Ein Objekt kann ein Array enthalten, dessen Elemente wiederum Objekte sind, und so weiter.

Diese Verschachtelbarkeit ist die zentrale Eigenschaft von JSON. Sie macht das Format ideal für APIs, Konfigurationsdateien und alles, was komplexe Datenmodelle abbildet. Ein typischer API-Response sieht so aus:

[
  {
    "id": 1,
    "name": "Anna Schmidt",
    "aktiv": true,
    "rollen": ["admin", "editor"]
  },
  {
    "id": 2,
    "name": "Jonas Becker",
    "aktiv": false,
    "rollen": ["viewer"]
  }
]

Was CSV ist

CSV (Comma-Separated Values) ist das genaue Gegenteil in puncto Struktur: ein flaches, zweidimensionales Raster aus Zeilen und Spalten. Jede Zeile ist ein Datensatz, jede Spalte ein Feld. Die erste Zeile enthält üblicherweise die Spaltenüberschriften. Trennzeichen ist klassisch das Komma, im deutschsprachigen Raum wegen des Dezimalkommas oft auch das Semikolon.

Das Format ist in RFC 4180 grob standardisiert, aber in der Praxis gibt es Varianten. Wichtig sind drei Regeln: Felder, die das Trennzeichen, ein Anführungszeichen oder einen Zeilenumbruch enthalten, müssen in doppelte Anführungszeichen eingeschlossen werden. Anführungszeichen innerhalb eines Feldes werden durch Verdopplung escaped. Und alle Zeilen sollten dieselbe Anzahl an Feldern haben.

CSV kennt keine Hierarchie und keine Datentypen. Alles ist Text. Genau diese Einfachheit ist der Grund, warum CSV von praktisch jeder Tabellenkalkulation, Datenbank und jedem BI-Tool gelesen werden kann.

Warum man JSON nach CSV konvertiert

Der häufigste Grund ist die Weiterverarbeitung in Werkzeugen, die mit Tabellen arbeiten, aber kein JSON verstehen oder es nur umständlich verarbeiten.

• Tabellenkalkulation: Excel, LibreOffice Calc und Google Sheets öffnen CSV direkt. Sortieren, filtern, Pivot-Tabellen und Formeln greifen sofort.
• BI- und Analyse-Tools: Power BI, Tableau und ähnliche Plattformen nehmen CSV als unkomplizierte Importquelle, besonders für einmalige Auswertungen ohne API-Anbindung.
• Datenimport in Datenbanken: Fast jedes Datenbanksystem hat einen Bulk-Import für CSV (COPY in PostgreSQL, LOAD DATA INFILE in MySQL). Das ist meist schneller und einfacher als zeilenweises Einfügen über eine Anwendung.
• Austausch mit Nicht-Technikern: Eine CSV-Datei kann jeder öffnen. Ein verschachtelter JSON-Baum überfordert Kolleginnen und Kollegen aus Fachabteilungen.

Die Konvertierung lohnt sich also überall dort, wo die hierarchische Macht von JSON nicht gebraucht wird, aber die Kompatibilität von CSV gefragt ist.

Wie die Umwandlung konzeptionell funktioniert

Das Grundprinzip ist überschaubar, wenn die JSON-Daten ein Array von flachen Objekten sind, also die typische Form einer Datensatzliste.

Objekte werden zu Zeilen. Jedes Element des äußeren Arrays entspricht einem Datensatz und damit einer Zeile in der CSV.

Keys werden zu Spalten. Die Schlüssel der Objekte bilden die Spaltenüberschriften. Der Konverter sammelt alle vorkommenden Keys und legt daraus den Header an.

Werte werden zu Zellen. Der Wert, der unter einem Key steht, landet in der Zelle am Schnittpunkt von Zeile und Spalte.

Für das obige Beispiel mit den ersten beiden flachen Feldern entsteht zunächst diese Zuordnung:

JSON-Konstrukt	CSV-Entsprechung
Äußeres Array	Gesamte Tabelle
Objekt im Array	Eine Datenzeile
Schlüssel (id, name)	Spaltenüberschrift
Wert eines Schlüssels	Zelleninhalt

Aus den beiden flachen Feldern id und name wird damit:

id,name
1,Anna Schmidt
2,Jonas Becker

So sauber funktioniert es allerdings nur, solange die Objekte flach sind und überall dieselben Keys haben. In echten Daten ist das selten der Fall, und genau dort beginnen die interessanten Entscheidungen.

Sonderfälle, die über Erfolg oder Datenverlust entscheiden

Verschachtelte Objekte

Wenn ein Wert selbst ein Objekt ist, gibt es keine direkte Spalte dafür. Zwei Strategien sind verbreitet. Beim Flatten mit Punkt-Notation wird der Pfad zum verschachtelten Feld zum Spaltennamen, also adresse.stadt und adresse.plz. Das erhält alle Werte und bleibt lesbar. Die Alternative ist, das innere Objekt als JSON-String in eine einzige Zelle zu schreiben. Das ist verlustfrei, aber die Zelle ist dann nicht mehr direkt auswertbar.

Arrays innerhalb eines Datensatzes

Ein Feld wie "rollen": ["admin", "editor"] passt nicht in eine einzelne flache Zelle, ohne eine Konvention festzulegen. Üblich ist das Join zu einem String mit einem Trennzeichen, das nicht mit dem CSV-Trennzeichen kollidiert, etwa admin|editor oder admin;editor. Alternativ wird das Array auf mehrere Spalten verteilt: rollen_0, rollen_1 und so weiter. Diese Variante ist heikel, weil die Spaltenzahl von der längsten Liste abhängt und bei kürzeren Listen leere Zellen entstehen.

Für das Eingangsbeispiel mit Join sieht das vollständige Ergebnis so aus:

id,name,aktiv,rollen
1,Anna Schmidt,true,admin|editor
2,Jonas Becker,false,viewer

Fehlende und zusätzliche Felder

CSV verlangt eine feste Spaltenmenge über alle Zeilen. Wenn ein Objekt Felder hat, die ein anderes nicht hat, muss der Konverter die Vereinigung aller Keys als Header bilden. Wo ein Objekt ein Feld nicht enthält, bleibt die Zelle leer. Wichtig ist die Unterscheidung zwischen einem fehlenden Feld und einem Feld mit dem Wert null. Beides landet in CSV oft als leere Zelle, obwohl es semantisch unterschiedlich ist. Wer diese Information braucht, muss eine eigene Konvention definieren, etwa den Literaltext null.

Datentypen

JSON unterscheidet Strings, Zahlen, Booleans und null. CSV kennt nur Text. Bei der Umwandlung gehen diese Typinformationen verloren, sofern das Zielsystem sie nicht selbst wieder rät. Drei Stolperfallen treten besonders oft auf:

JSON-Wert	Typisches CSV-Problem
true / false	Tabellenkalkulationen interpretieren das je nach Locale unterschiedlich
Zahl mit führender Null wie "00123"	Excel kann führende Nullen verwerfen
Dezimalzahl 3.14	Im deutschen Locale wird der Punkt eventuell nicht als Dezimaltrenner erkannt

Wer Zahlen mit führenden Nullen oder lange Ziffernfolgen wie Telefonnummern und IBANs hat, sollte beim Import in Excel die betroffenen Spalten explizit als Text deklarieren, statt die Datei per Doppelklick zu öffnen.

Escaping und Sonderzeichen

Sobald ein Wert das CSV-Trennzeichen, ein Anführungszeichen oder einen Zeilenumbruch enthält, muss das Feld korrekt gequotet und das Anführungszeichen verdoppelt werden. Ein Name wie Müller, Anna & "Co" wird zu "Müller, Anna & ""Co""". Diese Regel sauber umzusetzen ist der häufigste Punkt, an dem selbstgebaute Konverter scheitern. Ein Tool, das RFC 4180 folgt, nimmt einem das ab.

Die Umwandlung mit dem Browser-Tool json-csv.de

Für eine einmalige oder gelegentliche Konvertierung ist ein eigenes Skript oft Overkill. Das Browser-Tool json-csv.de macht den Prozess ohne Installation und ohne Server.

Der entscheidende technische Punkt: die Umwandlung läuft vollständig clientseitig im Browser. Das eingefügte JSON wird per JavaScript lokal geparst und in CSV überführt. Die Daten werden nicht hochgeladen und an keinen Server übertragen. Das ist relevant, sobald personenbezogene oder anderweitig sensible Daten im Spiel sind, denn die Information verlässt das eigene Gerät nicht.

Der Ablauf in der Praxis:

1. JSON in das Eingabefeld einfügen oder eine Datei auswählen.
2. Das Tool parst die Daten und erkennt die Struktur. Bei verschachtelten Objekten greift das Flatten mit Punkt-Notation, Arrays werden zusammengeführt.
3. Das Ergebnis erscheint als Vorschau und kann als CSV-Datei heruntergeladen werden.

Vor dem Einfügen lohnt ein kurzer Blick auf die eigene Datenstruktur. Liegt ein einzelnes Objekt statt eines Arrays vor, wird daraus eine CSV mit einer Datenzeile. Liegt ein tief verschachtelter Baum vor, sollte man vorher entscheiden, ob das Flatten oder ein vorbereitendes Umformen der Daten sinnvoller ist. Je flacher und gleichförmiger die JSON-Objekte sind, desto sauberer ist die resultierende Tabelle.

Worauf es ankommt

Die Umwandlung von JSON nach CSV ist im einfachen Fall trivial: Objekte werden Zeilen, Keys werden Spalten, Werte werden Zellen. Die Arbeit steckt in den Sonderfällen. Verschachtelte Objekte, Arrays innerhalb eines Datensatzes, uneinheitliche Felder und der Verlust von Typinformationen sind die Stellen, an denen Daten still verloren gehen oder ein Import kippt. Wer vorher festlegt, wie diese Fälle behandelt werden, und wer auf korrektes CSV-Escaping nach RFC 4180 achtet, bekommt eine Datei, die sich überall sauber importieren lässt. Für die schnelle, lokale Konvertierung ohne Datenabfluss ist ein clientseitiges Browser-Tool die pragmatische Wahl.