JSON zu CSV konvertieren: Anleitung mit Escaping-Regeln

Eine JSON-zu-CSV-Umwandlung nimmt ein Array flacher Objekte und macht daraus eine Tabelle: Jeder Schlüssel wird eine Spalte, jedes Objekt eine Zeile. Der Teil, der dabei am häufigsten schiefgeht, ist nicht die Grundidee, sondern das Escaping, also die Frage, was mit Werten passiert, die selbst ein Komma, ein Anführungszeichen oder einen Zeilenumbruch enthalten. Wer diese Regel einmal verstanden hat, weiß auch, warum eine bestimmte Zelle am Ende so aussieht, wie sie aussieht.

Warum CSV trotz JSON relevant bleibt

JSON ist das Standardformat für APIs und Konfigurationsdateien, aber sobald Daten in einer Tabellenkalkulation landen sollen, ist CSV weiterhin das gemeinsame Format. Excel, Google Sheets, Numbers, so gut wie jedes BI-Tool und jede Datenpipeline lesen CSV zuverlässig, während ein verschachteltes JSON-Objekt dort erst manuell auseinandergenommen werden müsste. Ein API-Export, den ein Kollege in Excel weiterverarbeiten soll, oder ein Datensatz, der in ein Analyse-Tool importiert wird, das kein JSON versteht, sind die typischen Anlässe für diese Umwandlung.

Beispiel: von JSON-Array zu CSV-Tabelle

Nimm folgendes JSON-Array mit drei Produktzeilen:

[
  { "sku": "A100", "product": "Wireless Mouse, Black", "price": 19.99, "in_stock": true },
  { "sku": "A101", "product": "17\" Laptop Stand", "price": 42.5, "in_stock": false },
  { "sku": "A102", "product": "USB-C Cable", "price": 8.99, "in_stock": true }
]

Die Umwandlung liefert:

sku,product,price,in_stock
A100,"Wireless Mouse, Black",19.99,true
A101,"17"" Laptop Stand",42.5,false
A102,USB-C Cable,8.99,true

Die Spaltenreihenfolge (sku, product, price, in_stock) entspricht der Reihenfolge, in der die Schlüssel zum ersten Mal im Array auftauchen. Jetzt zu den drei Zeilen im Detail, denn genau hier zeigt sich die Escaping-Logik.

In Zeile 1 enthält Wireless Mouse, Black ein Komma. Ein Komma ist in CSV das Feldtrennzeichen, also müsste ein Parser ohne weiteren Kontext an dieser Stelle ein neues Feld beginnen. Um das zu verhindern, wird der ganze Wert in doppelte Anführungszeichen eingeschlossen: "Wireless Mouse, Black". Innerhalb dieser Anführungszeichen ist das Komma dann nur noch Teil des Textes.

In Zeile 2 steckt der interessantere Fall: 17" Laptop Stand enthält ein einzelnes, literales doppeltes Anführungszeichen (nach der 17). Nach RFC 4180 gilt hier eine doppelte Regel: Erstens wird jedes Anführungszeichen im Wert verdoppelt, aus " wird "". Zweitens wird der gesamte Wert zusätzlich in ein äußeres Anführungszeichen-Paar eingeschlossen, weil er jetzt ein Anführungszeichen enthält. Das Ergebnis ist "17"" Laptop Stand", vier Anführungszeichen insgesamt: das äußere Paar, das den Wert umschließt, und das verdoppelte Zeichen für das ursprüngliche ". Ein CSV-Parser, der RFC 4180 beherrscht, liest daraus wieder korrekt 17" Laptop Stand.

In Zeile 3 ist USB-C Cable unauffällig: kein Komma, kein Anführungszeichen, kein Zeilenumbruch. Der Wert bleibt unquotiert, so wie A102 und 8.99 auch. Die Regel greift immer nur dann, wenn mindestens eines der drei Sonderzeichen im Wert vorkommt, alles andere bleibt schlank.

Fehlende Schlüssel: die Spaltenüberschrift ist eine Vereinigung

Ein naiver Konverter schaut nur auf das erste Objekt im Array und übernimmt dessen Schlüssel als Spalten. Taucht in einem späteren Objekt ein zusätzlicher Schlüssel auf, geht er stillschweigend verloren. Das Tool auf dieser Seite macht es anders: Die Spaltenüberschriften sind die Vereinigung aller Schlüssel, die irgendwo im Array vorkommen, in der Reihenfolge ihres ersten Auftretens. Ein Beispiel:

[
  { "name": "Anna", "city": "Berlin" },
  { "name": "Tom", "city": "München", "country": "Deutschland" }
]

Das erste Objekt kennt kein country. Trotzdem entsteht die Spalte, weil sie im zweiten Objekt auftaucht, und die fehlende Zelle in Annas Zeile bleibt einfach leer statt einen Fehler auszulösen:

name,city,country
Anna,Berlin,
Tom,München,Deutschland

Widget: JSON direkt hier umwandeln

Häufige Fehler

Verschachtelte Objekte werden zu [object Object]. Enthält ein Wert selbst ein Objekt, etwa "address": { "city": "Berlin", "zip": "10115" }, wird dieses Objekt in einen String umgewandelt, und das Ergebnis ist buchstäblich der Text [object Object] in der Zelle. Die eigentlichen Daten (Stadt, Postleitzahl) gehen dabei verloren, sie stecken einfach nicht mehr in der Ausgabe. Die Lösung ist, verschachtelte Objekte vor der Umwandlung selbst abzuflachen: aus address: { city, zip } werden zwei eigene Top-Level-Schlüssel address_city und address_zip, jeweils mit einem einfachen String- oder Zahlenwert.

Arrays werden zu einer kommagetrennten Zeichenkette, nicht zu eigenen Spalten. Ein Wert wie "tags": ["red", "blue"] wird zum String red,blue, ohne eckige Klammern. Weil dieser String jetzt selbst ein Komma enthält, greift die Escaping-Regel von oben, und die Zelle landet als "red,blue" in der CSV, eine einzelne Zelle mit zwei durch Komma getrennten Werten, keine zwei separaten Spalten. Wer stattdessen eine Spalte pro Tag will, muss das Array vorher selbst in einzelne Schlüssel auflösen, zum Beispiel tag_1, tag_2.

Die Excel-Falle mit dem Listentrennzeichen. Die Ausgabe dieses Tools verwendet ausschließlich das Komma als Trennzeichen, es gibt keine Semikolon-Option. In vielen deutschsprachigen Excel-Installationen ist aber das Komma als Dezimaltrennzeichen reserviert, weshalb Excel dort standardmäßig ein Semikolon als Listentrennzeichen für CSV-Dateien erwartet. Öffnest du eine kommabasierte CSV direkt per Doppelklick, landet der gesamte Inhalt einer Zeile oft in einer einzigen Spalte A statt sauber verteilt. Zwei Wege führen aus dieser Falle: entweder die Datei über “Daten > Text in Spalten” importieren und dort Komma explizit als Trennzeichen wählen, oder das Listentrennzeichen in den Windows-Regionseinstellungen von Semikolon auf Komma umstellen.

Ein einzelnes Objekt statt eines Arrays einfügen. Die Umwandlung erwartet ein JSON-Array, auch wenn nur eine einzige Zeile herauskommen soll. { "sku": "A100", "product": "Mouse" } ohne umschließende eckige Klammern ist kein gültiges Array und führt zu einem Fehler statt zu einer Ein-Zeilen-CSV. Die korrekte Form ist [{ "sku": "A100", "product": "Mouse" }], mit einem einzelnen Objekt innerhalb der Klammern.

Häufig gestellte Fragen

Welche JSON-Struktur akzeptiert das Tool? Ein Array flacher Objekte, also [{...}, {...}]. Ein einzelnes Objekt ohne umschließende eckige Klammern oder verschachtelte Strukturen ohne vorheriges Abflachen führen nicht zum gewünschten Ergebnis.

Was passiert, wenn ein Objekt einen Schlüssel nicht hat, den andere Objekte haben? Die Spaltenüberschriften sind die Vereinigung aller Schlüssel im gesamten Array, in der Reihenfolge ihres ersten Auftretens. Fehlt einem Objekt ein Schlüssel, bleibt die entsprechende Zelle in seiner Zeile einfach leer, es gibt keinen Fehler.

Warum erscheint in meiner CSV der Text [object Object]? Weil ein Wert selbst ein verschachteltes Objekt ist und beim Umwandeln in einen String zu dieser Platzhalter-Zeichenkette wird, ohne die eigentlichen inneren Daten mitzunehmen. Flache das Objekt vorher zu eigenen Top-Level-Schlüsseln ab, zum Beispiel address_city statt eines verschachtelten address-Objekts.

Warum öffnet meine CSV-Datei in Excel alles in einer Spalte? Weil deutschsprachige Excel-Installationen häufig ein Semikolon als Listentrennzeichen erwarten, während die Ausgabe hier ausschließlich Kommas verwendet. Nutze “Daten > Text in Spalten” mit Komma als gewähltem Trennzeichen, oder stelle das Listentrennzeichen in den Systemeinstellungen auf Komma um.

Werden meine Daten an einen Server gesendet? Nein. Die Umwandlung läuft vollständig im Browser, deine JSON-Daten verlassen dein Gerät zu keinem Zeitpunkt.

Kann ich das Tool auf meiner eigenen Seite einbetten? Ja. Auf der vollständigen Tool-Seite gibt es unter dem Widget den Umschalter “Dieses Tool einbetten”, der ein fertiges Code-Snippet mit <iframe> liefert. Das eingebettete Widget ist kostenlos, funktioniert eigenständig ohne zusätzlichen Seitenkontext, und über den Parameter ?theme=dark oder ?theme=light in der Embed-URL lässt sich das Farbschema festlegen.