Send a client a JSON file when they were expecting a spreadsheet, and you'll get a confused reply asking why the file won't open in Excel. Send an API a CSV when it wanted JSON, and it just won't work at all. Neither format is better than the other — they're built for different jobs, and picking the wrong one usually costs you an email chain you didn't need to have.
JSON and CSV are the two formats you'll run into constantly when exporting, importing, or sharing business data — client lists, product catalogs, invoice records, API responses. Most business software defaults to one or the other without asking, which is exactly why so many format mismatches happen in the first place. This guide covers what actually separates the two, when to reach for each one, and how to convert between them when you get handed the wrong format.
Photo by ThisIsEngineering on Pexels
What actually separates JSON from CSV
CSV (comma-separated values) is a flat grid: rows and columns, exactly like a spreadsheet, because that's essentially what it is in plain text form. Every row is a record, every column is a field, and there's no way to represent anything more complicated than that.
A row in CSV might look like name,email,total followed by Jane Doe,jane@example.com,450. Clean, but flat — there's no way to say "Jane has three orders" without repeating her name and email on three separate rows.
JSON (JavaScript Object Notation) is built for exactly that kind of nested relationship. The same customer can be represented once, with a list of orders attached directly to her record — data that mirrors how the information actually relates to itself, instead of being squeezed into a flat grid it doesn't naturally fit.
The size difference adds up fast. A customer list of 10,000 rows with five fields each might run roughly 500KB as CSV. The same data as JSON, with every field name repeated across all 10,000 records instead of listed once in a header row, can easily land at 1.5–2MB or more for identical information — a real difference if you're emailing the file or importing it somewhere with a size limit.
When to use CSV, and when to use JSON
The decision comes down to one question: is your data flat, or does it have relationships baked into it?
Use CSV when:
- You're exporting a customer list, transaction log, or anything else that's naturally one row per record.
- You're sending data to a client or teammate who's going to open it in Excel or Google Sheets — CSV opens instantly, no special software or technical explanation required.
- You're working with a large volume of simple records. CSV files are meaningfully smaller than the JSON equivalent, since JSON repeats every field name on every single record.
Use JSON when:
- Your data has real structure — an order with multiple line items, a contact with several phone numbers, anything where one record naturally contains a list of other things.
- You're talking to an API or a webhook. Nearly all of them speak JSON natively, not CSV.
- The data is going into a config file or a tool that expects structured settings rather than a flat table.
- The structure itself might change over time — JSON handles a new optional field showing up on some records but not others far more gracefully than CSV, which needs every row to share the same fixed set of columns.
Photo by Markus Spiske on Pexels
A quick gut check: if you could draw the data as a single table, one row per item, with nothing repeated in groups, it's CSV. If you find yourself needing a table inside a table, it's JSON.
Converting between them
You rarely need to convert by hand. Most spreadsheet software exports directly to CSV, and a JSON formatter will validate and clean up a JSON file so it's actually usable, whether you're reading it yourself or handing it off to someone else.
One thing worth knowing before converting JSON to CSV: nested structure doesn't survive the trip. If a customer record has three orders attached, converting straight to CSV either flattens each order into its own repeated row or drops the nested data outright, depending on the tool. Check the output before sending it anywhere that actually matters.
A common real scenario: moving data between two tools
Say you're connecting your invoicing tool to your bookkeeping software — through an automation platform like Zapier or Make, or just exporting from one and importing into the other by hand. The invoicing tool's API sends each invoice as JSON: a customer object, a list of line items, and a payment status, all nested together in one package, the same way most third-party business tools structure their data behind the scenes.
Your bookkeeping software might only accept a CSV import instead — one row per transaction, flat columns for date, amount, and category. That mismatch is normal, not a sign something's broken. Most automation platforms handle the conversion behind the scenes, but if you're doing it by hand, the line items are usually the part that gets lost or duplicated, since a flat CSV row can't hold "three items on one invoice" the way a nested JSON object can.
The practical fix is to flatten deliberately rather than let a conversion tool guess. Decide up front whether each line item becomes its own row, repeating the invoice number across all of them, or whether you only need invoice totals and can drop the line-item detail entirely. Knowing which one you actually need before converting saves a second round of cleanup afterward — and it's worth spot-checking a handful of rows against the original JSON the first time you set up a new export, rather than assuming the conversion did what you expected.
Frequently asked questions
What's the difference between JSON and CSV?
CSV is a flat grid of rows and columns, similar to a spreadsheet. JSON supports nested, hierarchical data — records that contain other records, like an order with multiple line items. CSV is simpler and smaller; JSON can represent more complex relationships.
When should I use CSV instead of JSON?
Use CSV when your data is naturally one row per record with no repeated groups, or when you're sending it to someone who will open it in Excel or Google Sheets. It's the safer default for straightforward business data like customer lists or transaction logs.
Can I convert JSON to CSV?
Yes, though nested data doesn't convert cleanly — a customer with three orders either gets flattened into three repeated rows or loses the nested structure entirely, depending on the tool. Check the output before relying on it for anything important.
Why are JSON files bigger than CSV files for the same data?
JSON repeats the field name for every single record — for example, "email" appears once per customer instead of once per file — which adds up across a large dataset. CSV only stores each column name once, in the header row.
Which format do most APIs use?
The overwhelming majority of REST APIs use JSON, since it naturally represents the kind of structured, nested data most applications work with internally.