How to Turn JSON Into CSV Without Losing the Useful Bits

JSON and CSV solve different problems.

JSON is comfortable with nested objects, arrays and hierarchical structures. This single decision — what each row represents — determines everything else. JSON nests naturally: an order can contain a list of line items, each with its own fields. CSV is flat, so you must choose how that hierarchy collapses. A file of orders can become one row per order (line items summarised into a cell) or one row per line item (order details repeated on each row). Neither is wrong; they answer different questions. Pick the grain before converting, because reshaping afterwards in a spreadsheet is far more painful.

CSV is comfortable with rows and columns.

The difficult part of converting JSON to CSV is usually not producing the file. It is deciding what one row represents and what to do with nested data.

Start by identifying the row

Before conversion, answer:

What does one row represent?

For example:

One row per customer.

Or:

One row per order.

Or:

One row per event.

If this is unclear, the resulting CSV may look tidy while representing the wrong data model. A common failure looks perfectly clean but is unusable: nested objects get flattened into columns like address.city and address.zip, while arrays get dumped into a single cell as "item1; item2; item3". The file opens fine, every row lines up, and yet you cannot pivot or filter on the array contents because they are trapped in one cell. If you need to analyse the nested data, explode it into rows first; if you only need it for reference, a joined cell is fine. Decide based on what you will actually do with the CSV. Two mechanical details cause a surprising number of broken CSVs. The first is values that contain the delimiter itself — an address or a product description with a comma in it — which splits one field into two unless the value is properly quoted. Good conversion wraps such fields in quotes automatically; if your columns suddenly shift right partway down the file, an unescaped comma is the usual culprit. The second is character encoding: names and symbols from non-English text can turn into garbled characters if the file is not saved as UTF-8, and spreadsheet programs sometimes guess the encoding wrong on open. Saving as UTF-8 and checking a row with special characters before you rely on the file avoids both.

Nested objects need a policy

Suppose one customer contains:

A flat CSV must decide how to represent those nested values.

Possibilities include:

There is no universal correct answer.

Inspect headers before exporting

Before opening the final CSV in a spreadsheet, inspect:

Use CSV when the next system is actually tabular

CSV works well for:

It can be a poor fit when the data is deeply nested or needs to preserve relationships between records.

A practical workflow

  1. Inspect the JSON structure.
  2. Decide the row.
  3. Decide how nested fields should be represented.
  4. Convert.
  5. Inspect headers.
  6. Check several records.
  7. Confirm delimiter and quoting.
  8. Keep the original JSON.

When not to convert

Keep JSON if:

Converting to CSV can be lossy in structure even when the visible values remain.

Flattening is a data-design choice

Flattening is not just formatting.

It changes how the information is represented.

Document the decision if another person will consume the CSV.

Watch delimiter and quoting rules

CSV fields can contain commas, quotation marks and line breaks.

A correct CSV writer handles these rules.

Do not assume that simply joining values with commas produces a robust CSV.

Keep the original JSON

The original is your source of truth.

The CSV is a derived representation.

The handoff test

Open the CSV in the software that will actually receive it.

Check:

Decide what must stay exact

If identifiers contain leading zeroes, make sure the receiving spreadsheet does not convert them into numbers.

For example:

`001245`

must not casually become:

`1245`

Tools used in this workflow

Primary tool: Json To Csv →

← All guides