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:

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-Text in eine einzige Zelle zu schreiben. Das ist verlustfrei, aber die Zelle ist dann nicht mehr direkt auswertbar. Der Konverter auf json-csv.de nimmt diese Form für Arrays, die Objekte enthalten.

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 (hier mit | als Trenner zwischen den Elementen) 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 Text null. Der Konverter auf json-csv.de bietet das als Option an.

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:

Wer Werte mit führenden Nullen oder lange Ziffernfolgen wie Telefonnummern hat, sollte beim Import in Excel die betroffenen Spalten explizit als Text deklarieren, statt die Datei per Doppelklick zu öffnen. Lange Zahlen gehören im JSON in Anführungszeichen, denn beim Einlesen werden ganze Zahlen über 9.007.199.254.740.991 gerundet.

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 Werkzeug, das RFC 4180 folgt, nimmt Ihnen das ab.

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

Für eine einmalige oder gelegentliche Konvertierung ist ein eigenes Skript oft Overkill. Der Konverter auf 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 gelesen und in CSV überführt. Die Daten werden nicht hochgeladen. Das ist relevant, sobald personenbezogene oder anderweitig sensible Daten im Spiel sind.

Der Ablauf in der Praxis:

1. JSON in das Eingabefeld einfügen oder eine Datei auswählen.
2. Der Konverter liest die Daten und erkennt Array, einzelnes Objekt oder JSON Lines. Verschachtelte Objekte werden mit Punkt-Pfad zu Spalten, für Arrays wählen Sie einen von vier Modi.
3. Trennzeichen, Kopfzeile und weitere Optionen stellen Sie ein, das Ergebnis erscheint sofort als Tabellenvorschau.
4. Kopieren oder als .csv herunterladen, bei Bedarf mit BOM für Excel.

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. Bei einem tief verschachtelten Baum sollten Sie vorher entscheiden, ob das Flachklopfen 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 Umwandlung ohne Upload ist ein Konverter im Browser die pragmatische Wahl.