JSON and CSV are the two formats most likely to be handed to you with the words "here's the data". They are both plain text, both human-readable, and they are good at almost opposite things. Choosing between them is rarely a matter of taste — it follows from three questions: how structured is the data, who consumes it, and what breaks when you choose wrong?
Structure: nested versus flat
JSON describes trees. An order can contain items, each item can contain options, and the structure says so explicitly, with types intact: numbers are numbers, booleans are booleans, null is null. CSV describes a grid. Rows and columns, everything a string, structure implied only by the header row. If your data has nesting, optional fields that vary per record, or types that matter, JSON expresses it natively and CSV forces you to flatten, join or — the usual compromise — stuff compact JSON into individual cells and apologise to whoever opens the spreadsheet.
Audience: machines versus people
APIs speak JSON; spreadsheets, accountants and quick email attachments speak CSV. CSV's superpower is that a non-programmer can open it in Excel and immediately sort, filter and chart it. JSON's superpower is that a program can parse it unambiguously with a one-liner in any language. A good rule: if the next consumer is software that needs the structure preserved, send JSON. If the next consumer is a person with a spreadsheet, send CSV — and if you are not sure, send the JSON and let tools convert, because going from structure to grid is easy and lossless-ish, while rebuilding a tree from a flattened grid is archaeology.
The failure modes
Pick CSV for nested data and you get delimiter roulette: values containing commas, quotes or newlines must be quoted exactly per convention, and one hand-rolled exporter that forgets will corrupt the file in ways that surface three columns later. Pick JSON for a quick human report and you get a wall of braces that nobody in finance will open twice. CSV also has no standard encoding story — a file in UTF-8 opened as Latin-1 turns names into mojibake — while JSON is UTF-8 by definition.
A compact decision guide
- API responses, configs, logs, anything nested → JSON.
- Spreadsheet handoffs, flat reports, bulk tabular imports → CSV.
- Data with mixed or optional fields per record → JSON (a CSV header built from the union of keys will be mostly empty cells).
- Huge flat streams you will process row by row → CSV (or JSON Lines, if you need types).
One more CSV hazard: helpful spreadsheets
If the CSV route is chosen, respect the spreadsheet's eagerness to reinterpret your data. Excel and its cousins will convert long numbers into scientific notation (destroying account numbers and IDs), strip leading zeros from postal codes, and turn strings that merely resemble dates — Mar-04, gene names in older research spreadsheets, version numbers — into actual dates, irreversibly, on open. The defences are dull but effective: quote fields that must stay literal, prefer importing through the wizard rather than double-clicking, and keep the JSON original as the source of truth so a mangled spreadsheet is an inconvenience, not a loss.
Most real workflows end up using both: JSON on the wire, CSV at the desk. That is not indecision — it is each format doing the job it was shaped for.
Try the tool behind this article: JSON to CSV Converter runs entirely in your browser — nothing you paste is uploaded.