JSON to CSV: How to Convert, and When Each Format Wins

JSON and CSV describe the same data in incompatible shapes: JSON is a tree that nests freely, CSV is a flat grid of rows and columns. Converting between them is therefore never just a format change — it’s a set of decisions about what to do with nesting, types and awkward characters. This guide walks through those decisions with a running example, then settles the “which format should I use?” question by use case. The converter itself is our JSON to CSV / CSV to JSON tool.

The shape problem

This JSON converts cleanly, because it’s already secretly a table:

[
  { "id": 1, "name": "Ada", "role": "admin" },
  { "id": 2, "name": "Grace", "role": "editor" }
]

id,name,role
1,Ada,admin
2,Grace,editor

The rules at work: the array becomes rows; the union of all object keys becomes the header; each object’s values fill its row. The moment the JSON isn’t a uniform array of flat objects, you have decisions to make — that’s most of this guide.

Decision 1: missing keys

[
  { "id": 1, "name": "Ada", "role": "admin" },
  { "id": 2, "name": "Grace" }
]

Grace has no role. In CSV the cell still has to exist — an empty field in her row (2,Grace,). The header is the union of keys across all rows, not just the first; converters that only read the first object silently drop keys that appear later. Check yours does the union.

Decision 2: quoting (RFC 4180)

A field must be wrapped in double quotes if it contains a comma, a double quote, or a line break — and a double quote inside a quoted field is written twice:

id,note
1,"He said ""hello, world"" and left"

Spreadsheets agree on these rules, which is why they’re the safe default. Two consequences people trip over: a field that looks numeric but contains a comma ("1,000") is text, and quoting everything is legal and often safer for hand-off files.

Decision 3: types become text

CSV has no types — every cell is a string. Conversion therefore destroys type information, and reverse conversion has to guess:

• 007 in a cell: a code, or the number 7 with padding? A conservative converter keeps it a string; an aggressive one hands you 7 and loses the zeros forever. (Our converter keeps 007 a string on the way back, deliberately.)
• true, 2026-10-23, 1e6, 3.0: all ambiguous. Dates are the worst — 03/04/2026 is March 4th or April 3rd depending on which side of the Atlantic wrote the file.
• Round-tripping JSON → CSV → JSON preserves shape, not types. If exact types matter, CSV is a presentation format for the data, not a storage format for it.

Decision 4: nested values

{ "id": 1, "tags": ["vip", "beta"], "address": { "city": "Perth" } }

There is no cell-shaped hole for an array or an object. Your three honest options:

1. Flatten objects into dotted columns (address.city) — good for one level of nesting, explodes combinatorially beyond that.
2. Serialise the nested value as JSON text inside the cell ("[""vip"",""beta""]") — lossless, ugly, fine for machine consumers.
3. Refuse — if the data is genuinely a tree, CSV is the wrong target; keep JSON. A converter that silently stringifies with [object Object] (JavaScript’s default) has chosen a fourth, dishonest option: check yours doesn’t.

CSV to JSON: the reverse trip

The header row becomes keys; each following row becomes an object. The traps mirror the forward ones: duplicate headers (the second name column overwrites or must be renamed), rows with more or fewer cells than the header, and the type-guessing problem above. Sensible defaults: strings everywhere unless a value is unambiguously numeric, empty cell → empty string (not null, unless you choose otherwise and document it).

When each format wins

The short version: CSV is JSON’s flatland — perfect when your data really is a grid, lossy the moment it isn’t. Convert deliberately, keep the original, and if you validate the JSON first (our validation guide covers the common breakage), the conversion has one less class of surprise waiting.