How to convert nested JSON to CSV

2026-09-22 · 7 min read

The awkward part of this conversion is not the syntax. It is that CSV is a grid and JSON is a tree, so something has to give. Understanding what gets flattened, and how, saves you from a spreadsheet that quietly lost half the data.

The easy case

An array of flat objects maps onto CSV perfectly. Each object is a row, each key is a column. If every object has the same keys, there is nothing to decide.

Nested objects become dotted columns

When a value is itself an object, the usual convention is to join the path with a dot. An address object containing city and country becomes two columns, address.city and address.country. Nothing is lost and the header row tells you the original shape.

JSON	CSV columns
{"id":1,"address":{"city":"Lyon"}}	id, address.city
{"id":1,"tags":["a","b"]}	id, tags (joined) or tags.0, tags.1
Objects with different keys	Union of all keys, blanks where absent

Arrays are where you have to choose

An array inside a row has no natural grid representation, and there are three common answers. Each is right for a different purpose.

Join the values into one cell, separated by a semicolon or a pipe. Keeps one row per record, which is what you want for a quick look in a spreadsheet.
Expand into indexed columns: tags.0, tags.1, tags.2. Keeps values separate but produces a ragged header when records have different lengths.
Explode into multiple rows, repeating the parent fields. This is what a database person expects, and it is the right shape for a pivot table, but the row count no longer matches the record count.

If you are going to pivot or group the result, exploding into rows is almost always the right choice. If you are going to read it, joining into one cell is. Deciding after the export is more work than deciding before it.

Records that do not share keys

Real API responses often contain objects with optional fields. A converter has to take the union of every key it sees, which means scanning the whole document before it can write the header row. Rows missing a key get an empty cell, which is not the same as a null, and that distinction matters if you plan to filter on it.

Things that break in spreadsheets afterwards

Long numeric IDs get rendered in scientific notation, and leading zeros disappear. Treat ID columns as text on import.
Values that look like dates get reformatted by the spreadsheet, not by the converter.
A value containing a comma, a quote or a newline must be quoted in the CSV. A converter that does not quote correctly produces a file that opens misaligned.

Doing it locally

JSON that needs converting is usually an export from a system you work on, which means it holds customer fields or internal identifiers. The converter here runs in the browser, so the document is parsed in the tab and never uploaded. The reverse direction is available too if you need to go back from a spreadsheet to JSON.

Frequently asked questions

What happens to an array inside a record?

You choose: join it into a single cell, expand it into indexed columns, or explode it into several rows that repeat the parent fields. Exploding suits pivots and grouping; joining suits reading.

Why did my IDs turn into scientific notation?

That is the spreadsheet, not the conversion. Import the column as text rather than letting the spreadsheet guess, or the long digits get treated as a number.

What if my objects do not all have the same keys?

The converter takes the union of all keys and leaves a blank cell where a record lacks one. A blank is not the same as an explicit null, which matters if you filter on it later.