🔄 Format & Conversion · 7 min read

CSV vs JSON: What's the Difference and Which to Use

CSV stores one flat table of rows and columns as plain text; JSON stores key-value data that can nest objects and lists and remembers types. Use CSV when the data is a single rectangular table headed for a spreadsheet, a database import or a bulk upload. Use JSON when the data is structured — fields that nest, values that repeat, numbers and true/false that should not be flattened to text. The choice follows the shape of your data, not the popularity of the format.

Both are text formats you can open in a plain editor, and both are small compared with a spreadsheet file. The differences that decide real work are nesting, data types, and what happens to a long number when it passes through.

The quick answer

If you can draw your data as a table where every row has the same columns, CSV is the right container. If any record has its own sub-fields, a list of items, or values that must stay numbers or booleans, JSON is the right container. When in doubt, ask which is one table: CSV. Which is a tree: JSON.

CSV vs JSON at a glance

What CSV is good at

• Spreadsheets and imports. A CSV opens in Excel, Google Sheets, Numbers or LibreOffice with no import step, and loads into most databases and CRMs through a plain upload.
• One row per record, one line per row. That line-per-record rule is why a CSV can be streamed, split or read by line without a full parser, and why it stays readable at a glance.
• No ceremony. The file is the data and little else, so it stays small and diffs are understandable in version control.

What JSON is good at

• Nested records. An order with several line items, or a user with an address and a list of roles, fits JSON directly and only awkwardly in a table.
• Real types.A JSON number is a number and a JSON boolean is true or false, so a reader does not have to guess whether "false" means the boolean, the string, or a missing value.
• APIs. Almost every web service returns JSON, so keeping data in JSON avoids a conversion step on the way in or out.

Where CSV breaks

No types means silent edits. A CSV has no way to say that a column is text, so a tool that guesses will turn 00123 into 123, and a 16-digit ID into scientific notation. The fixes are covered in keeping leading zeros and in why CSV IDs turn into 1.23E+15.

The delimiter is a guess. A file saved with semicolons is read as one column by a tool expecting commas. That is a CSV-only failure, and the recovery path is in why a CSV opens in one column.

One table only. The instant a record needs a sub-list, CSV forces a workaround: repeat the parent values on every line, or pack several values into one cell and split them later. Both are fine until a value contains the character you split on.

Where JSON breaks

Big integers lose a digit. JSON itself does not fix a numeric range, and in JavaScript and many other readers a JSON number becomes a double-precision float. That means integers above 2 to the power of 53 are no longer exact — the ECMAScript reference names the largest safe integer Number.MAX_SAFE_INTEGER, which is 9007199254740991, and anything at 9007199254740992 or higher can be off by one. Long account numbers, order IDs and national ID numbers should live in JSON as strings, exactly as they should be quoted to survive a trip through Excel.

No comments and no trailing commas. JSON has no comment syntax and no decimal or date type, so a currency amount or a timestamp is either a number or a string and the meaning lives in the reader. RFC 8259 is explicit that a JSON text is a serialised value and nothing more.

It is easier for a human to mis-read. A flat table of a thousand rows is quick to scan; the same data as nested JSON is not, which is why a CSV copy is still the format people open to check the numbers.

Converting between them

A flat JSON array of objects becomes a CSV table directly, one object per row. Going the other way, a CSV becomes a JSON array of objects keyed by the header row. Both directions are one click in the browser:

• CSV to JSON — turn a table of rows into a JSON array for an API, a script or a config file.
• JSON to CSV — flatten an API response back into a table you can open in a spreadsheet.
• Excel to JSON — go straight from a workbook without exporting a CSV first.

One honest note: nesting does not round-trip. A JSON object with a nested address, converted to CSV, comes back as columns like address.city. Convert it back and you get a key whose name contains a dot, not a nested object. If the nesting matters, keep the original JSON — the CSV is a flattened view of it.

How to choose

1. Draw the data. One table of same-shaped rows → CSV. Any record with its own parts or a list → JSON.
2. Name the destination. A spreadsheet, a CSV importer or a bulk database load wants CSV. A web API or an app wants JSON.
3. Check the long numbers. If any column holds IDs, account numbers or zip codes, make sure they survive as text — in CSV by quoting, in JSON by storing strings.
4. Keep the source. If you converted one to the other, keep the original alongside it, because the conversion is lossy in one direction for nested data.

Frequently asked questions

The CSV rules referenced here are from RFC 4180 and the JSON rules from RFC 8259, both retrieved from the RFC Editor on the day this page was published. The precise-integer limit is the value documented as Number.MAX_SAFE_INTEGER (2 to the power of 53 minus 1 equals 9007199254740991) in the ECMAScript and MDN references. No other figures are quoted, because none is documented in a single source we could verify.