CSV vs. JSON – Definition and Differences
Compare flat delimited text with structured JSON: nesting, types, size, streaming, tooling, and which to choose for collected data.
Both are text formats for exchanging data. CSV describes a table; JSON describes a structure. That single difference drives every other trade-off.
1. Key Differences
| Dimension | CSV | JSON |
|---|---|---|
| Structure | Flat rows and columns | Nested objects and arrays |
| Types | Everything is text | Strings, numbers, booleans, null |
| Schema | External, by agreement | Implicit in the document |
| Null handling | Ambiguous | Explicit null |
| Size | Compact — no repeated keys | Larger — keys repeat per record |
| Encoding | Undeclared | UTF-8 by default |
| Spreadsheet support | Native | Poor |
| Streaming | Line by line | Whole document, unless JSON Lines |
2. Where CSV Wins
- Size. No repeated keys makes it markedly smaller for wide tabular data.
- Human handoff. It opens in a spreadsheet, which matters more than engineers expect.
- Simplicity for genuinely flat data.
- Universal tooling, including command-line text utilities.
3. Where JSON Wins
- Nesting. Lists within records, records within records — impossible in CSV without flattening.
- Types survive. Numbers stay numbers; booleans stay booleans.
- Null is unambiguous, distinct from empty string.
- Self-describing. Field names travel with the data.
- API-native, so no conversion is needed at the boundary.
4. JSON Lines Resolves the Streaming Gap
One JSON object per line combines JSON's structure with CSV's streaming and appendability:
{"title": "Widget", "price": 49.9, "tags": ["a","b"]}
{"title": "Gadget", "price": 12.0, "tags": []}
It can be appended to, processed line by line, and split across files — which is why it has become the default for collected data at scale.
5. Choosing for Collected Data
- Nested fields present? JSON Lines. Flattening nested data into CSV loses information or explodes column counts.
- Flat and going to a person? CSV, with a documented schema.
- Large and going to analysis? Parquet, which beats both on size and type fidelity.
- Feeding an API? JSON, matching what the consumer expects.
6. Converting Between Them
JSON to CSV requires flattening, which is lossy: nested arrays must be joined or exploded, and either choice discards structure. CSV to JSON requires typing, which is guesswork without a declared schema.
The practical rule is to keep the richer format as the source of truth and generate the flatter one as an export, never the reverse.
7. Common Mistakes
- Flattening nested data into CSV and losing relationships.
- Inferring types from CSV, turning identifiers into numbers.
- Writing one enormous JSON array that cannot be streamed or appended.
- Assuming CSV encoding, since it declares none.
- Treating empty and null as the same in CSV, where they are indistinguishable.
8. Summary
CSV is compact, flat, and spreadsheet-friendly with no types and no declared encoding. JSON is structured, typed, and self-describing at the cost of size.
For collected data, JSON Lines is usually the right default — structure and types with line-based streaming — with CSV generated as an export for people and Parquet adopted when scale makes size and typing matter more.