How to Convert JSON to CSV (A Practical Guide)

JSON and CSV solve different problems. JSON is built for nested, hierarchical data — objects inside objects, arrays of objects, optional fields. CSV is built for one thing: a flat grid, rows and columns, the format every spreadsheet tool and most data-import pipelines actually expect. Converting between them sounds trivial until your JSON has a nested address object or an array of tags, and suddenly "just convert it" isn't obvious anymore.

This is a practical walkthrough of what actually happens during a JSON-to-CSV conversion, the decisions a good converter has to make on your behalf, and the mistakes that cause corrupted spreadsheets down the line.

The core problem: flattening

CSV has no concept of nesting. So the first real job of any JSON-to-CSV converter is flattening — turning a nested structure into flat column names. The standard convention is dot notation for objects and bracket notation for arrays:

{
  "id": 1,
  "name": "Ada",
  "address": { "city": "London", "zip": "E1" },
  "tags": ["engineer", "mathematician"]
}

becomes columns:

id, name, address.city, address.zip, tags[0], tags[1]

This is the part that trips up naive conversion scripts. A converter that doesn't flatten will either throw an error on the first nested object it sees, or — worse — silently stringify it as "[object Object]", corrupting your data without telling you.

Arrays of objects: the harder case

Flattening a single nested object is straightforward. The genuinely hard case is an array of objects — a list of line_items, a list of authors, anything where the array length varies between records. There's no universally "correct" answer here; a good converter needs to make a defensible choice and be consistent about it (typically: index-based column names, like items[0].sku, items[1].sku, padding with blanks for shorter arrays).

Type inference going the other direction

The reverse conversion — CSV back to JSON — has its own trap. Every value in a CSV file is, technically, a string. "42", "true", "" are just text until something decides otherwise. A converter that doesn't do type inference will hand you back a JSON file where every single field is a string, including numbers and booleans — which breaks anything downstream that expects a real type.

Good CSV-to-JSON conversion detects numbers, booleans, and empty cells (as null) automatically, and gives you the option to turn that off when you genuinely want everything kept as a literal string (IDs with leading zeros are the classic case where automatic number conversion actively hurts you — "007" becoming 7 is a real bug, not a feature).

The delimiter and encoding traps

Two smaller but common gotchas:

• Delimiter conflicts. If a text field contains a comma, a naive converter will silently split it into two columns. Correct CSV output quotes any field containing the delimiter, a quote character, or a newline.
• Excel and the BOM. Excel on Windows won't correctly detect UTF-8 encoding in a CSV without a byte-order-mark (BOM) at the start of the file — without it, accented characters and non-Latin text render as garbled symbols the moment someone opens the file in Excel.