Convert JSON to CSV: Complete Guide With Examples

Wann Sie eine JSON-zu-CSV-Konvertierung benötigen

JSON ist das Standardformat für APIs und Webanwendungen, aber sobald Daten das Entwickler-Ökosystem verlassen müssen — in eine Tabelle, ein Business-Intelligence-Tool, einen Datenbank-Import oder einen Bericht, der an einen Stakeholder per E-Mail gesendet wird — ist CSV normalerweise das erwartete Format.

Häufige Szenarien, in denen eine JSON-zu-CSV-Konvertierung erforderlich ist:

• Exportieren von API-Daten — Abrufen von Datensätzen aus einer REST-API und Laden in Excel oder Google Sheets zur Analyse.
• Datenbankimporte — Viele Datenbanken (PostgreSQL, MySQL, SQLite) unterstützen CSV-Importe standardmäßig, aber nicht JSON.
• Berichterstattung — Nicht-technische Stakeholder benötigen Daten in einem Format, das sie in einer Tabelle öffnen können, nicht in einem JSON-Viewer.
• Datenpipelines — Legacy-ETL-Systeme erwarten oft CSV als Austauschformat zwischen den Phasen.

Versuchen Sie es selbst: Fügen Sie ein JSON-Array in unseren JSON zu CSV Konverter ein, um eine sofort herunterladbare CSV-Datei zu erhalten.

Einfache Konvertierungsanleitung

Der unkomplizierte Fall: Sie haben ein JSON-Array flacher Objekte, bei denen jedes Objekt die gleichen Schlüssel hat. Dies lässt sich direkt in eine CSV-Tabelle umwandeln.

Eingabe-JSON:

[
  { "name": "Alice", "age": 30, "city": "Portland" },
  { "name": "Bob", "age": 25, "city": "Seattle" },
  { "name": "Carol", "age": 35, "city": "Denver" }
]

Ausgabe-CSV:

name,age,city
Alice,30,Portland
Bob,25,Seattle
Carol,35,Denver

Die Objekt-Schlüssel werden zu Spaltenüberschriften, und jedes Objekt wird zu einer Zeile. Dies ist der einfache Weg — und es funktioniert perfekt für die meisten API-Antworten, die Arrays von Datensätzen zurückgeben.

Die Komplexität tritt auf, wenn Ihr JSON nicht flach ist. Verschachtelte Objekte, Arrays innerhalb von Objekten, fehlende Schlüssel und gemischte Typen erfordern Entscheidungen darüber, wie hierarchische Daten in einer flachen Tabelle dargestellt werden.

Umgang mit verschachteltem JSON

Echtes JSON ist selten flach. Eine API-Antwort für einen Benutzer könnte ein verschachteltes Adressobjekt, ein Array von Rollen und optionale Felder enthalten, die nicht in jedem Datensatz erscheinen. CSV hat kein Konzept der Verschachtelung, daher benötigen Sie eine Flattening-Strategie.

Strategie 1: Punktnotation

Der gebräuchlichste Ansatz. Verschachtelte Schlüssel werden mit Punkten verknüpft, um einen einzelnen Spaltennamen zu bilden.

Eingabe:

[
  {
    "name": "Alice",
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  }
]

Ausgabe:

name,address.city,address.state
Alice,Portland,OR

Die Punktnotation bewahrt die strukturelle Beziehung im Spaltennamen. Sie funktioniert gut für ein oder zwei Ebenen der Verschachtelung, wird jedoch unhandlich bei tief verschachtelten Daten (user.profile.settings.notifications.email).

Strategie 2: Separate Spalten pro Blattwert

Ähnlich wie die Punktnotation, jedoch mit benutzerdefinierten Spaltennamen, die die Verschachtelungshierarchie weglassen. Zum Beispiel wird address.city einfach zu city. Dies erzeugt sauberere Überschriften, erfordert jedoch eine manuelle Spaltenzuordnung und birgt das Risiko von Namenskonflikten, wenn verschiedene verschachtelte Objekte Schlüssel mit demselben Namen haben.

Strategie 3: Verschachtelte Objekte als String darstellen

Für komplexe verschachtelte Strukturen, die sich nicht gut in flache Spalten umwandeln lassen, serialisieren Sie den verschachtelten Wert als JSON-String innerhalb der CSV-Zelle.

Ausgabe:

name,address
Alice,"{""city"":""Portland"",""state"":""OR""}"
Bob,"{""city"":""Seattle"",""state"":""WA""}"

Dies bewahrt alle Daten, aber die CSV-Zellen enthalten rohes JSON — nicht ideal für Tabellenbenutzer. Es funktioniert, wenn die CSV ein Zwischenformat ist, das später wieder von Code geparst wird.

Vergleich der Flattening-Ansätze

Ansatz	Lesbarkeit	Datenverlust	Tiefe Verschachtelung	Am besten geeignet
Punktnotation	Gut	Keine	Wird ausführlich	1-2 Ebenen der Verschachtelung
Benutzerdefinierte Spaltennamen	Am besten	Mögliche Kollisionen	Manueller Aufwand	Bekannte, stabile Schemata
Stringifizieren	Schlecht für Menschen	Keine	Handhabt jede Tiefe	Maschinen-zu-Maschinen-Pipelines

Umgang mit Arrays innerhalb von Objekten

Arrays stellen eine andere Herausforderung dar. Betrachten Sie einen Benutzer mit mehreren Rollen:

{
  "name": "Alice",
  "roles": ["admin", "editor", "viewer"]
}

Sie haben mehrere Optionen, um dies in CSV darzustellen:

• Als durch Trennzeichen getrennte Zeichenfolge zusammenfassen: admin;editor;viewer in einer einzigen Zelle. Einfach, erfordert jedoch späteres Parsen.
• Separate Spalten: roles.0, roles.1, roles.2. Funktioniert, wenn die maximale Array-Länge bekannt und klein ist.
• Separate Zeilen: Eine Zeile pro Rolle, wobei die anderen Daten des Benutzers wiederholt werden. Dies denormalisiert die Daten, vermeidet jedoch Mehrwertzellen.
• Stringifizieren: ["admin","editor","viewer"] als rohes JSON in der Zelle. Bewahrt die Struktur für eine spätere Verarbeitung.

Die richtige Wahl hängt davon ab, wer die CSV konsumiert. Für Tabellenbenutzer ist der Ansatz mit durch Trennzeichen getrennten Zeichenfolgen normalerweise am praktischsten. Für Datenpipelines bewahrt das Stringifizieren die meisten Informationen.

Randfälle

Jede JSON-zu-CSV-Konvertierung trifft irgendwann auf diese Fälle. Im Voraus darüber Bescheid zu wissen, spart Debugging-Zeit.

Null-Werte

JSON null kann einer leeren Zelle, dem wörtlichen String null oder einem benutzerdefinierten Platzhalter zugeordnet werden. Die meisten Tools verwenden eine leere Zelle, was für Tabellen korrekt ist, aber die Unterscheidung zwischen "null" (explizit kein Wert) und "fehlendem Schlüssel" (Feld nicht vorhanden) verliert. Wenn diese Unterscheidung wichtig ist, verwenden Sie null als wörtlichen String.

Gemischte Typen

Ein JSON-Feld könnte in einem Datensatz ein String und in einem anderen eine Zahl sein. CSV-Spalten haben keine Typen — alles ist ein String — daher funktioniert dies normalerweise auf CSV-Ebene gut. Das Problem tritt auf, wenn in typisierte Systeme (Datenbanken, typisierte DataFrames) importiert wird. Validieren Sie die Typen nach der Konvertierung.

Fehlende Schlüssel

Wenn Objekte in einem JSON-Array nicht alle die gleichen Schlüssel haben, muss der Konverter eine Vereinigung aller Schlüssel über alle Objekte hinweg erstellen. Dies erzeugt eine Kopfzeile mit jeder möglichen Spalte, und Objekte, die einen Schlüssel vermissen, erhalten eine leere Zelle für diese Spalte.

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "city": "Seattle" }
]

Ausgabe:

name,age,city
Alice,30,
Bob,,Seattle

Sonderzeichen in Werten

CSV-Werte, die Kommas, doppelte Anführungszeichen oder Zeilenumbrüche enthalten, müssen in doppelte Anführungszeichen gesetzt werden. Wenn der Wert selbst doppelte Anführungszeichen enthält, werden diese durch Verdopplung escaped. Die meisten Konvertierungsbibliotheken behandeln dies automatisch, aber wenn Sie Ihren eigenen Konverter erstellen, ist dies die häufigste Fehlerquelle.

name,bio
Alice,"Liebt ""JSON"" und Programmieren"
Bob,"Portland, OR"

Programmatische Konvertierung

JavaScript / Node.js

Für einfache flache Daten können Sie JSON in wenigen Zeilen ohne Abhängigkeiten in CSV umwandeln:

const jsonToCsv = (data: Record<string, unknown>[]) => {
  if (data.length === 0) return "";

  const headers = Object.keys(data[0]);
  const rows = data.map((row) =>
    headers
      .map((header) => {
        const value = row[header] ?? "";
        const str = String(value);
        return str.includes(",") || str.includes('"') || str.includes("\\n")
          ? `"\${str.replace(/"/g, '""')}"` 
          : str;
      })
      .join(",")
  );

  return [headers.join(","), ...rows].join("\\n");
};

Für den Produktionsgebrauch mit verschachtelten Daten behandeln Bibliotheken wie json2csv (aus dem @json2csv/plainjs-Paket) das Flattening, benutzerdefinierte Transformationen und Randfälle:

import { Parser } from "@json2csv/plainjs";
import { flatten } from "@json2csv/transforms";

const parser = new Parser({
  transforms: [flatten({ separator: "." })],
});

const csv = parser.parse(data);

Python

Die Standardbibliothek von Python hat alles, was Sie für grundlegende Konvertierungen benötigen:

import csv
import json
import io

def json_to_csv(data: list[dict]) -> str:
    if not data:
        return ""

    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=data[0].keys())
    writer.writeheader()
    writer.writerows(data)
    return output.getvalue()

Für verschachteltes JSON flacht die pandas-Bibliothek in einem Aufruf ab und konvertiert:

import pandas as pd

df = pd.json_normalize(data, sep=".")
df.to_csv("output.csv", index=False)

json_normalize behandelt automatisch verschachtelte Objekte und verwendet Punktnotation für Spaltennamen. Es ist der schnellste Weg, von einer verschachtelten API-Antwort zu einer sauberen CSV-Datei zu gelangen.

Überlegungen zu großen Dateien

Wenn Ihre JSON-Datei Hunderte von Megabyte oder mehr umfasst, muss sich der Konvertierungsansatz ändern. Das gesamte Datei in den Speicher zu laden, sie zu parsen und eine CSV-Zeichenfolge im Speicher zu erstellen, kann leicht Ihren verfügbaren RAM überschreiten.

Streaming-Parser sind die Lösung. Anstatt die gesamte Datei zu laden, verarbeiten sie sie inkrementell:

• Node.js: Verwenden Sie JSONStream oder stream-json, um das JSON-Array objektweise zu parsen, jedes in eine CSV-Zeile umzuwandeln und in einen Ausgabestrom zu schreiben. Der Speicher bleibt konstant, unabhängig von der Dateigröße.
• Python: Die ijson-Bibliothek bietet iteratives JSON-Parsen. Kombinieren Sie es mit csv.writer, der in ein Datei-Handle schreibt, für eine konstant speichereffiziente Konvertierung.
• CLI: jq verarbeitet JSON nativ im Streaming-Modus. Für JSON-zu-CSV speziell sind Tools wie miller (mlr) und csvkit für großflächige Formatkonvertierungen konzipiert.

Eine praktische Faustregel: Wenn Ihre JSON-Datei unter 50 MB liegt, ist die Konvertierung im Speicher in Ordnung. Darüber hinaus sollten Sie zu einem Streaming-Ansatz wechseln. Über 1 GB verwenden Sie ein CLI-Tool wie miller oder ein dediziertes Datenverarbeitungsframework.

Die richtige Vorgehensweise wählen

Szenario	Empfohlene Vorgehensweise
Schnelle einmalige Konvertierung	Online-Tool oder Browser-Konverter
Flaches JSON, kleine Dateien	Eingebaute Sprachbibliothek (csv-Modul, einfache JS-Funktion)
Verschachteltes JSON, komplexes Schema	pandas.json_normalize oder @json2csv mit Flatten-Transformation
Große Dateien (>50 MB)	Streaming-Parser (ijson, stream-json) oder CLI (miller)
Wiederkehrende Pipeline	Skript mit einer Bibliothek, in CI/ETL integriert

Für die meisten Entwickler ist der schnelle Konvertierungsweg alles, was sie benötigen. JSON einfügen, CSV erhalten, weitermachen. Die Komplexität ist nur dann von Bedeutung, wenn die Daten verschachtelt sind, die Dateien groß sind oder die Konvertierung unbeaufsichtigt in einer Pipeline abläuft.

Versuchen Sie es selbst: Fügen Sie Ihre JSON-Daten in unseren JSON zu CSV Konverter ein, um in wenigen Sekunden eine saubere CSV-Datei zu erhalten. Müssen Sie den umgekehrten Weg gehen? Verwenden Sie unser CSV zu JSON Tool.