JSON to CSV

Last updated June 2026 · Maintained by the JSONNeat author

The input shape

The converter expects a JSON array where each element is an object — the same shape almost every API uses to return a list of records. It walks the array once, builds a header row from the union of keys it sees, and writes one CSV row per element. Missing fields become empty cells; extra fields extend the header.

[
  {"id": 1, "name": "Ada",   "role": "engineer"},
  {"id": 2, "name": "Linus", "role": "kernel"},
  {"id": 3, "name": "Grace", "role": "compiler"}
]

Converts to:

id,name,role
1,Ada,engineer
2,Linus,kernel
3,Grace,compiler

What "flat" means and why it matters

CSV is a two-dimensional format — rows and columns of scalar values. JSON is a tree. The mismatch shows up the moment your objects contain nested objects or arrays. Consider:

[
  {"id": 1, "name": "Ada", "address": {"city": "London", "country": "UK"}, "skills": ["math", "computing"]}
]

There is no canonical way to put address and skills into single cells. JSONNeat picks the safest option — it JSON-stringifies the nested value into the cell verbatim. You get anaddress column with the value {"city":"London","country":"UK"} and askills column with ["math","computing"]. The data is preserved exactly, but Excel can't sort, filter or chart by it.

The clean alternative is to flatten the JSON before converting — turn nested keys into dot-separated column names:

[
  {"id": 1, "name": "Ada", "address.city": "London", "address.country": "UK", "skills": "math,computing"}
]

Flattening is opinionated (how do you handle arrays of objects? What separator between path segments?) so JSONNeat leaves that decision to you. A one-liner with jq or the Python pandas.json_normalize function does the job consistently. Our blog has a worked example in REST API JSON best practices.

CSV escaping rules, in case you ever need to write them yourself

The converter follows RFC 4180, the de facto CSV standard. The rules are simple:

1. Fields are separated by commas.
2. Rows are separated by CRLF (\r\n).
3. If a field contains a comma, double quote, CR or LF, the entire field is wrapped in double quotes.
4. Any double quote inside a quoted field is doubled — he said "hi" becomes"he said ""hi""".
5. No escape for backslash, no escape for tab. CSV is much simpler than JSON in this regard, which makes it brittle but also predictable.

The converter handles all five cases automatically. You should never have to edit the output by hand to make it open correctly in Excel or Google Sheets.

Common pitfalls

• "Cannot convert: input must be an array of objects." Your JSON is either a single object, a single value, or an array of non-object values. Wrap a single object in [ ], or restructure your data so the rows are explicit.
• Header row in unexpected order. Headers appear in first-seen order. If you want alphabetical headers, sort the keys in each object first, or post-process the output in a spreadsheet.
• Numbers shown as text in Excel. Long numeric IDs (16+ digits) can be auto-formatted by Excel as exponential notation, losing precision. Import via Data → From Text and explicitly mark those columns as Text, or prefix the value with a leading apostrophe when generating the JSON.
• Special characters look wrong in Excel. CSV doesn't carry an encoding. Save with UTF-8 and open via Data → From Text/CSV to be safe. Google Sheets and Numbers handle UTF-8 correctly by default.
• Output opens in one column. Your Excel locale uses semicolons as separators. Either use Data → Text to Columns, or save with a .csv extension and import via the menu rather than double-clicking.

When CSV is the wrong target format

CSV is great for flat, tabular data with mostly scalar values. It struggles or fails for:

• Hierarchical data. Org charts, file trees, AST representations — anything where the shape is the data. Stay in JSON or use a graph-oriented format.
• Mixed schemas. If half your objects have type: "user" with one set of fields and the other half have type: "event" with a completely different set, the CSV ends up mostly empty cells. Split into two CSVs by type first.
• Binary data. CSV is text. Base64-encode binary fields in the JSON before converting, or use a binary-friendly format like Parquet or Avro.
• Large datasets that need columnar access. Parquet, ORC and Arrow are dramatically more efficient for analytics workloads. CSV is fine up to a few hundred MB; beyond that, switch.

Privacy

The converter runs entirely in your browser. JSON pasted into the editor is not uploaded, logged or cached on JSONNeat's servers — safe for converting analytics exports, customer data, or production records that you would not want to leave your machine.