7 min read

How to convert JSON to CSV

A practical guide to converting JSON arrays of objects into CSV for spreadsheets, reporting, and imports.

Table of contents

  1. The best JSON shape for CSV
  2. How headers are chosen
  3. CSV escaping rules
  4. A safe conversion workflow

The best JSON shape for CSV

CSV is a table format. It works best when the source data is also table-like. In JSON, that usually means a top-level array where each item is an object with similar keys. Each object becomes one row, and the keys become column headers.

If your JSON is a single object, an array of strings, or a deeply nested tree, you need to reshape it before the CSV can be useful. CSV has rows and columns; JSON can describe almost any hierarchy.

How headers are chosen

A converter usually collects object keys and uses them as the header row. When some objects have keys that others do not, the CSV will include all discovered columns and leave missing values empty. This is practical for flexible API responses, but consistent data produces cleaner spreadsheets.

Before converting, check key names. Keys that are fine for code may not be clear to spreadsheet users. Renaming fields before export can make the CSV easier to understand.

CSV escaping rules

CSV values containing commas, quotes, or line breaks must be quoted. Quotes inside values are usually escaped by doubling them. A good converter handles this automatically so values do not shift into the wrong columns.

If you open the CSV in a spreadsheet and columns look misaligned, check whether the original values contained commas or line breaks and whether they were escaped correctly.

A safe conversion workflow

Validate the JSON first. Confirm it is an array of objects. Convert to CSV. Then scan the header row and a few sample rows before sharing or importing the file. If nested values appear as JSON strings, decide whether that is acceptable or whether those fields should be flattened.

For small datasets, an online converter is enough. For production exports, implement a consistent export pipeline so column order, types, and escaping are controlled.

Related guides

FAQ

What JSON converts best to CSV?

A top-level array of flat objects converts best to CSV.

What happens to nested objects?

Nested objects need flattening or stringification, depending on the converter.

Can arrays be CSV columns?

They can be stringified or expanded, but there is no single universal rule.

Should I validate JSON first?

Yes. Conversion should start with valid JSON.