Guide · 6 min read
JSON vs CSV: choosing a data format
CSV and JSON solve the same problem from opposite directions. CSV is a flat grid that any spreadsheet can open. JSON is a nested tree with real types that any programming language can parse. Most integration pain comes from forcing one to behave like the other.
Where CSV wins
CSV is tiny, streams line by line and opens in tools non-technical colleagues already use. For a flat table of a million rows, it is smaller and faster to process than the equivalent JSON, because the field names are written once in the header rather than repeated in every record.
Where JSON wins
JSON carries types — numbers, booleans and null are distinct from strings — and supports nesting and arrays. An order with several line items is one natural JSON object and an awkward set of repeated CSV rows.
The quoting rules that bite
A CSV field containing a comma, a quote or a newline must be wrapped in double quotes, and an internal quote is doubled. Naive exports that just join values with commas break the moment an address or a free-text comment appears. When you convert between formats, use a parser that implements these rules rather than a split on commas.
Flattening nested data
To move JSON into CSV you have to flatten. Dot-path column names such as customer.address.city are the common convention, and they round-trip predictably. Arrays are harder: either explode them into multiple rows or serialise them into a single cell and accept the loss of structure.
A practical rule
Use CSV when a human will open the file or when the data is genuinely tabular. Use JSON when a program will consume it or when the records nest. If you need both, keep JSON as the source of truth and generate CSV on demand.