Nested JSON converts to CSV by keeping each top-level record as one row and writing any nested object or array into a single cell as JSON text. That way no data is lost, even though a CSV can only hold a flat table.
This guide shows how the JSON to CSV converter treats each kind of nesting, why it works that way, and how to reshape your JSON when you need nested values in separate columns.
On this page
Key takeaways
- Top-level objects become rows; nested objects and arrays become JSON text inside one cell.
- An object that wraps one list, such as { "results": [...] }, is unwrapped automatically.
- An object holding several lists produces one CSV file per list.
- To get nested fields as their own columns, flatten them in the JSON before converting.
Steps shown in the video
- Click Choose JSON Files and select your JSON file
- Your file is listed with its size
- Click Convert to CSV
- Download your .csv file
Why can't CSV store nested data?
A CSV file is one table: every row has the same columns, and every cell holds a single value. JSON, defined in RFC 8259, allows objects inside objects and lists of any length. Something has to give when the two meet, and the converter's choice is to preserve the data rather than guess at a layout.
Nested objects
An object inside a record becomes JSON text in one cell. The column is named after the key that holds it.
[
{ "id": 7, "name": "Ana", "address": { "city": "Lisbon", "zip": "1100-148" } }
]id,name,address
7,Ana,"{""city"":""Lisbon"",""zip"":""1100-148""}"The doubled quotes are standard CSV escaping. When you open the file in Excel, the address cell shows {"city":"Lisbon","zip":"1100-148"}.
Arrays inside records
A list inside a record, such as tags or line items, is also written as JSON text in one cell: ["new","sale"]. A spreadsheet formula or a later import can split it again if needed.
If the whole file is an array of arrays, such as [[1, "a"], [2, "b"]], each inner array becomes one row as it is. No header row is added, because there are no keys to name the columns.
API responses with wrapper objects
| Top-level JSON | Result |
|---|---|
| { "results": [ {...}, {...} ] } | The results list becomes the table |
| { "users": [...], "orders": [...] } | yourfile_users.csv and yourfile_orders.csv, downloaded together as a ZIP |
| { "total": 2, "results": [...] } | Treated as one record, because not every value is a list |
How to get nested fields in their own columns
When you need address.city and address.zip as separate columns, flatten the JSON before converting. A few lines of code do it:
const flat = rows.map(({ address, ...rest }) => ({
...rest,
address_city: address?.city ?? null,
address_zip: address?.zip ?? null,
}));Save the result as JSON and convert it. Each nested field now has its own column. If you plan to analyse the data in Excel, JSON to Excel applies the same rules and creates a workbook directly.
Before you open the CSV
Nested values often include commas and quotes, so make sure your spreadsheet reads the file as UTF-8 and comma-separated. Our guide to fixing special characters and broken values in Excel covers the details, and the step-by-step JSON to CSV guide walks through a full conversion.
Nested JSON to CSV: FAQ
Can nested JSON be converted to CSV?
Yes. Each top-level record becomes a row, and nested objects or arrays are written into one cell as JSON text.
How do I flatten nested JSON into separate columns?
Copy the nested fields into top-level keys, for example address_city, before converting. A short script or a spreadsheet formula can do it.
What happens to arrays inside JSON records?
They are stored as JSON text in a single cell, such as ["new","sale"].
Why did I get several CSV files?
Your JSON is an object containing several lists. Each list becomes its own CSV, named after its key.
Does the converter lose any data?
No. Values that do not fit a flat cell are kept as JSON text instead of being dropped.
Flat output, nothing lost
Writing nested values as JSON text keeps every piece of data while producing a valid CSV. When you need nested fields in their own columns, flatten them first and convert again.
