JSON to CSV Tutorial: Convert Arrays to Spreadsheet Rows

Q: What happens to nested objects when converting JSON to CSV?

CSV is a flat format with no nesting, so nested JSON objects must be flattened before conversion. The most common convention is dot notation: a nested field like {"address": {"city": "Paris"}} becomes a column header address.city with the value Paris. Some converters use an underscore separator (address_city) instead. Arrays inside objects are harder — they have variable length and no natural single-column representation. A common workaround is to serialize array values as a delimited string (e.g., "red,green,blue") within one cell, but this makes the CSV harder to use in spreadsheet tools. For deeply nested data with arrays of objects, CSV is a poor fit and JSON is the better format.

Q: How do I handle arrays in JSON to CSV conversion?

Arrays of primitive values (strings, numbers) can be joined into a single cell with a delimiter like a pipe or semicolon. Arrays of objects are more complex — you either flatten them using indexed column names (items.0.name, items.1.name) or denormalize by repeating the parent row for each array item. The best approach depends on how the CSV will be used. For spreadsheet analysis, denormalization works well. For imports back into a database, indexed column names preserve structure. If the array length varies across records, indexed columns leave many cells empty for shorter arrays. When arrays are central to the data model, consider whether CSV is the right output format at all.

Q: What if JSON objects have different keys?

When JSON objects in an array have different keys — for example, some objects have a "team" field and others do not — the CSV header row should be the union of all keys found across every object. Scan all objects before writing the header row to collect every unique key. Objects that lack a given key should produce an empty cell for that column. Using only the first object to determine headers is a common mistake that causes later objects to truncate or misalign. Most CSV converter libraries handle this automatically, but if you are writing your own conversion code, collect all headers first in one pass before writing any rows.

Q: How do I set the CSV delimiter?

The default CSV delimiter is a comma, as the name implies. However, many regions and spreadsheet tools use a semicolon (;) or tab character as the delimiter instead. European Excel installations default to semicolons because commas are used as decimal separators in some locales. TSV (Tab Separated Values) uses a tab and is common in data pipelines where commas appear in data values. When generating a CSV, you can specify the delimiter in most libraries — for example, PapaParse accepts a delimiter option, and Python csv.writer accepts a dialect or delimiter argument. When opening the file in Excel, you can specify the delimiter in the import wizard.

Q: Does JSON to CSV work with deeply nested data?

JSON to CSV conversion works poorly with deeply nested data. CSV is a two-dimensional format (rows and columns), while deeply nested JSON can have arbitrary depth. Flattening 3 or 4 levels of nesting produces very long column header names that are hard to read and work with in spreadsheets. Arrays of objects nested inside arrays of objects require either very wide tables with indexed column names or multiple output CSV files. If your JSON data is deeply nested by design, it is a signal that CSV is not the right output format. Consider keeping it as JSON for downstream processing or converting to a database with proper foreign-key relationships.

Q: What tool converts JSON to CSV fastest?

For browser-based conversion, Jsonic's JSON to CSV tool handles files instantly in your browser without uploading data to a server. For command-line use, jq with @csv output filter is extremely fast: jq -r '(.[0] | keys_unsorted) as $keys | $keys, (.[] | [.[$keys[]]] | @csv)' input.json. For Python, the json and csv standard library modules are fast for moderate file sizes. For very large files (100MB+), the command-line tool csvkit (csvjson command) or DuckDB can query and export JSON to CSV with high performance. For Node.js scripts, the json2csv package offers streaming conversion that handles large files without loading everything into memory.

Last updated: May 11, 2026

JSON to CSV conversion maps each object in a flat array to 1 CSV row and each key to a column header — a 100-object array with 5 keys produces a 100-row, 5-column CSV in under 10 ms. Nested JSON requires a flattening step first: {"user": {"name": "Alice"}} must become {"user.name": "Alice"} before the column can be written. JavaScript needs about 5 lines with Object.keys and Array.map; Python's csv.DictWriter handles it natively; the json2csv npm package handles 8 edge cases automatically. This guide covers flat array conversion, nested object flattening, arrays-of-arrays, header extraction across mismatched objects, quoting commas and newlines in cell values, and null vs empty string handling.

Start with a JSON array of objects

CSV is a table format, so the cleanest input is a list of similar records.

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com",
    "active": true
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com",
    "active": false
  }
]

id,name,email,active
1,Alice,alice@example.com,true
2,Bob,bob@example.com,false

Choose CSV headers

Headers usually come from the union of keys across all objects. If the first object does not include every key, scan the whole array before writing the header row.

[
  { "id": 1, "name": "Alice" },
  { "id": 2, "name": "Bob", "team": "Support" }
]

// Headers should be: id,name,team

Flatten nested JSON objects

CSV cannot store nested objects directly. A common convention is dot notation.

[
  {
    "id": 1,
    "name": "Alice",
    "address": {
      "city": "Paris",
      "country": "FR"
    }
  }
]

// id,name,address.city,address.country
// 1,Alice,Paris,FR

Escape commas, quotes, and newlines

CSV values that contain commas, double quotes, or line breaks must be wrapped in double quotes. Double quotes inside the value are escaped by doubling them.

[
  { "note": "Hello, world" },
  { "note": "She said \"yes\"" }
]

// note
// "Hello, world"
// "She said ""yes"""

Common JSON to CSV mistakes

Trying to convert one deeply nested object without deciding what the rows are.
Using only the first object to determine headers when later rows have extra keys.
Flattening arrays into ambiguous text without a delimiter convention.
Forgetting that spreadsheet apps may reinterpret IDs, dates, and long numbers.

Convert JSON to CSV online

Paste a JSON array into Jsonic's JSON to CSV converter to flatten nested objects, copy the CSV, or download a spreadsheet-ready file.

Open JSON to CSV

Frequently asked questions

What happens to nested objects when converting JSON to CSV?

Nested objects must be flattened. The standard convention is dot notation: a nested field like address.city is written as a column header in the CSV output. Deeply nested structures or arrays of objects inside objects are poor fits for CSV and may need a different output format.

How do I handle arrays in JSON to CSV conversion?

Arrays of primitives can be joined into one cell with a delimiter. Arrays of objects can be flattened with indexed column names (items.0.name) or denormalized by repeating the parent row per array item. If arrays are central to the data model, CSV may not be the right format.

What if JSON objects have different keys?

Use the union of all keys across every object as the header row. Scan all objects before writing headers. Objects missing a key produce an empty cell. Using only the first object for headers is a common mistake that misaligns data in later rows.

How do I set the CSV delimiter?

The default is a comma. Use semicolons for European locales where commas are decimal separators. Use tabs for TSV files common in data pipelines. Most libraries accept a delimiter option — PapaParse, Python csv.writer, and most online tools all support custom delimiters.

Does JSON to CSV work with deeply nested data?

Poorly. CSV is two-dimensional. Three or more levels of nesting produce unreadably long column names. Arrays of objects nested inside arrays require indexed columns that leave many cells empty. Deeply nested JSON is usually better kept as JSON or stored in a relational database.

What tool converts JSON to CSV fastest?

Jsonic converts JSON to CSV in the browser instantly. For the command line, jq with @csv is very fast. For large files (100MB+), DuckDB or csvkit handle streaming conversion. The json2csv Node.js package supports streaming for large files without loading everything into memory.