How to Convert JSON to CSV
CSV is a flat table; JSON is a tree. Conversion works cleanly only when your JSON is an array of flat objects. Here is exactly how the mapping works and where it breaks.
The shape that converts cleanly
A table has rows and columns, so CSV conversion expects a JSON array of objects, where each object is one row and each key is a column:
[
{ "id": 1, "name": "Ada", "active": true },
{ "id": 2, "name": "Linus", "active": false }
]becomes:
id,name,active
1,Ada,true
2,Linus,falseHow the columns are chosen
The column header row is the set of keys. If every object has the same keys, the mapping is exact. If objects have different keys, a correct converter takes the union of all keys and leaves missing cells blank — so always check that row 1's headers cover every field you expect.
Nested objects and arrays
CSV cells are scalar, so a value like "roles": ["admin","dev"] or "address": {"city":"NYC"} has no single-cell form. Converters handle this in one of three ways: flatten the path into a column (address.city), join arrays into one cell ("admin;dev"), or dump the raw JSON into the cell. Decide which you want before converting, because each breaks differently downstream.
Quoting and the gotchas that corrupt the file
Any value that itself contains a comma, a double quote, or a newline must be wrapped in double quotes, and internal quotes doubled: He said "hi" becomes "He said ""hi""". A converter that skips this shifts every column after the offending cell — the classic "my spreadsheet is misaligned" bug. Booleans become the bare words true/false, and null usually becomes an empty cell.
FAQ
Why does my JSON-to-CSV output only have one column?
Your JSON is probably a single object or an array of non-objects. CSV conversion needs an array of objects, where each object becomes a row and its keys become the columns.
How are nested objects handled in CSV?
CSV cells can only hold scalars, so nested objects and arrays must be flattened into dotted columns (address.city), joined into one cell, or stored as raw JSON text. Pick the behaviour before converting.
What happens to a value that contains a comma?
It must be wrapped in double quotes in the CSV, e.g. "Paris, France". Otherwise the comma is read as a column separator and every following column shifts over.