How to Convert CSV to JSON (and Back) Without Fighting a Spreadsheet

You’ve got a CSV and something wants JSON — an API, a config file, a data import. Or the reverse: a JSON export and you need it as CSV so you can open it in a spreadsheet. It sounds trivial, and for clean data it is. For real-world data, a naive converter mangles it.

The Simple Case

A CSV with a header row maps directly to an array of objects. This:

name,role,active
Ada,Engineer,true
Grace,Admiral,true

becomes:

[{"name":"Ada","role":"Engineer","active":true},
{"name":"Grace","role":"Admiral","active":true}]

If your data is that tidy, a five-line script does it. In Python: import csv, json; json.dump(list(csv.DictReader(open('data.csv'))), open('out.json','w')). Most spreadsheet apps and code editors can do it too.

The Gotchas That Break Naive Converters

Commas inside fields. "Smith, Jr." is one field, not two — a naive split on commas destroys the row. Proper CSV parsing respects quotes.
Newlines inside fields. A quoted field can contain line breaks (addresses, notes). Splitting on line breaks shreds it.
Types. Should active be the boolean true or the string "true"? Is 007 the number 7 or the string "007"? Getting this wrong silently corrupts data downstream.
Inconsistent columns and stray blank lines, which break row alignment.
Encoding & BOM — a UTF-8 byte-order mark can turn your first header into name and break the key.

The $1 version

When you don’t want to write and debug a parser — or you’re round-tripping messy data with quoted commas and mixed types — CSV ↔ JSON converts cleanly in both directions for $1: proper quote handling, sensible typing, header-to-key mapping. Agents can call the same endpoint over x402.

Going the Other Way (JSON → CSV)

JSON to CSV has its own trap: nesting. A flat array of flat objects maps cleanly to rows and columns. But if your objects contain nested objects or arrays ("address": {"city": "..."}), there’s no single obvious CSV shape — you have to flatten (e.g. address.city as a column) or serialize the nested part. Decide that on purpose rather than letting a converter guess.

FAQ

What’s the fastest free way for a clean file?

A short script (Python’s csv + json modules), or your code editor’s built-in conversion. Clean data with a header row converts in seconds.

Why did my converter split a name into two columns?

It split on every comma instead of respecting quoted fields. "Smith, Jr." needs a real CSV parser that honors the quotes.

Can it handle nested JSON?

Going to CSV, nested structures have to be flattened or serialized — there’s no lossless single-table form. Going from CSV, you get a flat array of objects.

The Takeaway

For clean data, a few lines of code convert CSV↔JSON for free — use them. When the data has quoted commas, embedded newlines, mixed types, or you just want it done right in one step, use the $1 CSV↔JSON converter, or see the full $1 tools catalog.