JSON vs. YAML vs. CSV: Picking the Right Data Format
All three can technically hold the same data. Here's what each one is actually optimized for, and the YAML mistake that silently changes meaning instead of throwing an error.
Key takeaways
- CSV is the right choice for flat, tabular data — spreadsheets, exports, anything with uniform rows and columns.
- JSON is the right choice for nested, hierarchical data, and for anything an API needs to consume directly.
- YAML is the right choice for human-edited configuration — the same data model as JSON, written for people.
- CSV has no standard way to represent nested structure; JSON and YAML both handle it natively.
- YAML's whitespace-sensitive syntax is also its biggest liability — a wrong indent silently changes meaning instead of throwing an error.
Same data, three different jobs
It's easy to pick a data format out of habit rather than fit, especially since all three of these can technically represent the same underlying information — a list of records with fields. What actually differs is who or what each format is optimized for: humans reading rows in a spreadsheet (CSV), machines exchanging structured data (JSON), or humans hand-editing configuration (YAML).
CSV: flat, and only flat
CSV's strength is exactly its simplicity: rows and columns, opens instantly in Excel or Google Sheets, universally supported, and remarkably compact for tabular data. Its weakness is the same simplicity — there's no standard way to represent a nested object or a list within a single field. Workarounds exist (a JSON string crammed into one cell, custom delimiter conventions) but they're fragile and don't round-trip cleanly between tools.
JSON: built for machines, readable enough for humans
JSON natively supports nesting and arrays, and it's the near-universal format for API requests and responses across essentially every programming language. Its strict syntax — quoted keys, no trailing commas, no comments — trades away some human-friendliness in exchange for being parsed identically, with zero ambiguity, by every language and tool that reads it.
YAML: JSON's data model, written for people
YAML represents essentially the same tree of objects, arrays, and scalar values as JSON, just written with indentation instead of braces, without requiring quotes around most values, and — critically — with support for comments. That's exactly why configuration files (CI pipelines, Kubernetes manifests, docker-compose files) are almost always written in YAML rather than raw JSON: someone has to hand-edit these, and comments plus not having to count matching braces genuinely help.
“YAML and JSON aren't really rivals — YAML is JSON's data model wearing more comfortable clothes.”
The trade-off YAML doesn't advertise
YAML's readability comes directly from significant whitespace, and that's exactly where it bites people: an indent off by a single space can silently change which parent object a key belongs to, instead of raising an obvious syntax error the way a missing brace would in JSON. It's worth validating YAML by actually parsing it — not just eyeballing the indentation — especially before it goes anywhere near a deploy pipeline.
Convert between them without losing structure
Open Tools Library's CSV to JSON Converter follows the RFC 4180 spec, correctly handling quoted commas and embedded newlines inside fields rather than breaking on them, and the YAML to JSON Converter lets you confirm a config actually parses to the structure you expect before it ships. Both run entirely client-side — useful for turning a spreadsheet export into API-ready JSON, or sanity-checking a YAML file's real structure before it goes into production.
Mentioned in this post
CSV ⇄ JSON Converter
Convert CSV to JSON or JSON to CSV, both directions, with a proper RFC 4180-compliant parser that handles quoted fields, embedded commas and newlines, auto-detected delimiters, and header rows — entirely in your browser.
Markdown Converter
Convert Markdown to HTML or HTML back to Markdown with a live sandboxed preview, then export the same Markdown as a real PDF, Word (.docx), HTML, or plain text file — support for headings, lists, links, images, code blocks, blockquotes, and tables, entirely in your browser.
YAML ⇄ JSON Converter
Convert YAML to JSON or JSON to YAML, both directions, with support for nested mappings and sequences, flow-style collections, quoted strings, comments, and correct re-quoting on output — entirely in your browser.
Frequently asked questions
Can CSV represent nested data?
Not natively. Common workarounds — embedding a JSON string in a cell, custom delimiter conventions — exist but are fragile and don't round-trip cleanly between tools.
Is YAML just JSON with different syntax?
Largely yes at the data-model level — the same trees of objects, arrays, and scalars — plus support for comments and mostly unquoted values, which JSON doesn't allow.
Why do config files use YAML instead of JSON?
Mainly comments and not having to count matching braces — both genuinely help when a human is hand-editing the file, which config files usually are.
What's the most common YAML mistake?
Inconsistent or incorrect indentation, which can silently change which object a key nests under instead of raising a syntax error — always worth validating by parsing, not just reading.