Data
JSON vs YAML vs CSV: Which Format Should You Use?
JSON, YAML and CSV all do the same basic thing: they store data as plain text you can open, read and share. But they were designed for different jobs, and picking the wrong one turns a simple task into a frustrating one. This guide walks through what each format is good at, where it falls down, and how to decide between them.
JSON: the language of the web
JSON (JavaScript Object Notation) is everywhere. If you have ever called an API, your app almost certainly sent or received JSON. It stores data as key-value pairs and arrays, which can be nested as deeply as you like — perfect for structured, hierarchical data.
JSON also carries real data types: strings, numbers, booleans (true/false), null, objects, and arrays. A program reading JSON knows that 42 is a number and "42" is text, with no guessing. The trade-off is that its syntax is strict: every quote, comma and bracket has to be exactly right, and a single trailing comma breaks the whole file. JSON also has no comments, so you cannot leave notes inside the data. That strictness is a feature for machine-to-machine communication, where predictability matters more than friendliness.
YAML: built for humans
YAML is, in effect, a superset of JSON aimed at people rather than machines. Instead of braces and brackets, it uses indentation to show structure, which makes it far easier to read and edit by hand. It also supports comments (lines starting with #), so you can explain what a setting does right next to it.
That readability is why YAML dominates configuration files — you will find it in Docker Compose, GitHub Actions and other CI pipelines, and Kubernetes manifests. The catch is that YAML is whitespace-sensitive: a stray space or a tab where a space belongs can silently change the meaning or break the file entirely. It is wonderful to read and surprisingly easy to get subtly wrong.
CSV: simple rows and columns
CSV (Comma-Separated Values) is the oldest and simplest of the three. It stores flat, tabular data — rows and columns, like a spreadsheet — and in fact it opens directly in Excel, Google Sheets or Numbers with no conversion. Files are tiny and dead simple to generate.
The limitations follow from that simplicity. CSV has no nesting, so it cannot represent hierarchical data the way JSON and YAML can. It has no real data types — everything is just text, and whether 007 stays 007 or becomes 7 depends on whatever opens it. And the format has real pitfalls: values that contain commas or line breaks need careful quoting, and character-encoding mismatches can turn names and symbols into gibberish.
Side-by-side comparison
| Format | Best for | Nesting | Comments | Human-readable | Typical use |
|---|---|---|---|---|---|
| JSON | Structured data exchange | Yes | No | OK | APIs, web apps |
| YAML | Hand-edited configuration | Yes | Yes | Excellent | Docker, CI, Kubernetes |
| CSV | Flat tabular data | No | No | Good | Spreadsheets, exports |
So which should you use?
The right choice usually falls out of the job:
- Use JSON when programs need to talk to each other — APIs, web front-ends, and anywhere strict, typed, nested data matters.
- Use YAML when a human will read and edit the file by hand, especially configuration where comments help. Keep an eye on your indentation.
- Use CSV when your data is a simple table and the destination is a spreadsheet or a quick import. Don't reach for it the moment you need nesting or reliable types.
The takeaway
There is no single best format — only the best fit for the task in front of you. JSON for machines, YAML for humans editing config, CSV for simple tables headed to a spreadsheet. And when you have data in one shape but need it in another, you do not have to rewrite it by hand: you can convert between all three in a single click.