JSON vs YAML vs CSV: When to Use Which
JSON, YAML and CSV all store data as plain text, and it is tempting to treat them as interchangeable. They are not. Each makes different promises about types, structure and who is expected to edit the file, and most conversion bugs come from assuming one format keeps a promise that only another one makes.
Three formats, three design goals
JSON was designed for machines to exchange data. Its grammar is tiny: objects, arrays, strings, numbers, true, false and null. Nearly every language ships a parser, and because the rules are strict, two parsers almost always agree on what a document means.
YAML was designed for people to write configuration. It drops braces and most quotes in favour of indentation, allows comments, and adds conveniences such as multi-line strings and anchors for reuse. The price is a much larger specification, and parsers differ more than you would hope.
CSV is the odd one out. It is not a data model at all, just rows of text split on a delimiter. It exists because spreadsheets and databases can export tables, and a table is all it can express.
Data types: what each format actually knows
JSON has six kinds of value and keeps them distinct: "42" is a string and 42 is a number. YAML has the same model, but it infers the type from unquoted text, so what you meant and what the parser decides can differ. CSV has no types whatsoever. Every cell is a string, and any number, date or boolean you see is an interpretation applied later by whatever reads the file.
| Feature | JSON | YAML | CSV |
|---|---|---|---|
| Typed values | Yes, six types | Yes, inferred from text | No, everything is text |
| Comments | No | Yes (#) | No (not in the common dialect) |
| Nesting | Arbitrary depth | Arbitrary depth | None, flat rows only |
| Human editing | Fair | Good, until indentation bites | Good in a spreadsheet |
| Size on disk | Medium, repeats keys | Medium to small | Smallest for tables |
| Parser agreement | High | Lower | Varies by dialect |
Nesting and size
If your data has a shape, such as an order containing line items that each contain a product, JSON or YAML is the natural fit. CSV can only represent that by flattening it, either into several files joined on an id or into awkward column names like address.city.
For a plain table with a million rows, CSV wins on size because column names appear once in the header. JSON repeats every key on every record, which inflates the file and compresses well but still costs memory when parsed. YAML is usually a little smaller than pretty-printed JSON for the same document because it omits braces and quotes, but nobody picks YAML for bulk data.
YAML gotchas that bite in production
The most famous is the Norway problem. In YAML 1.1, which many parsers still follow, the unquoted values no, off and n are booleans. A list of country codes therefore turns Norway into false:
countries:
- SE
- NO # parsed as the boolean false in YAML 1.1
- DK
version: 1.10 # parsed as the float 1.1
zip: 01234 # may be read as an octal number
when: 2026-01-05 # may become a date object, not a string
The fix is to quote anything that must stay a string: "NO", "1.10", "01234". The JSON to YAML converter does this for you in one direction. Its documentation says strings that YAML would otherwise read as another type, such as "true", "null", "1e3" or "2026-01-01", are quoted in the output so they survive a round trip.
The second class of problem is whitespace. YAML indentation is structural, tabs are not allowed for indentation, and a single misaligned line can silently change which key a value belongs to instead of raising an error. Use spaces, keep a consistent width, and validate the result by converting it to JSON where the structure is explicit. The JSON to YAML converter also converts YAML back to JSON and points to the line of a syntax error, which is a quick way to see what a parser really made of your file.
Finally, remember that YAML anchors and aliases are a feature JSON lacks. When a YAML file is converted to JSON they are expanded into plain repeated values, and comments are discarded because JSON cannot hold them. Multi-document files separated by --- become a JSON array with one element per document.
CSV gotchas: quoting, delimiters and lost types
A CSV cell that contains a comma, a double quote or a line break must be wrapped in double quotes, and a literal quote inside it is doubled. So He said "hi", then left becomes "He said ""hi"", then left". Hand-written splitting on commas breaks the first time someone types an address with a comma in it.
Delimiters are not universal either. In several European locales spreadsheets export with semicolons because the comma is the decimal separator. Tab-separated files are common too. When a file arrives as one wide column, the delimiter is almost always the culprit.
The deepest problem is that CSV loses types. A column of identifiers like 00420 looks numeric, and a reader that infers types will turn it into 420 and drop the leading zeros. The CSV to JSON converter offers header detection, custom delimiters, quoted-field handling and type inference, and its documentation recommends turning inference off for columns that must stay text, such as postcodes, phone numbers and ids.
Conversion pitfalls to expect
- JSON to CSV flattens. Nested objects become dotted columns such as
address.city, and arrays become indexed columns or a joined string. Going back does not always rebuild the original shape. - Ragged records. If objects in a JSON array have different keys, the CSV needs the union of all keys and many cells will be empty.
- Empty is ambiguous. An empty CSV cell could mean an empty string, null or a missing value. JSON distinguishes all three, so decide a convention up front.
- Big numbers. JSON itself has no integer limit, but JavaScript parsers read numbers as 64-bit floats, so ids above 9,007,199,254,740,991 lose precision. Send such ids as strings.
- Dates. None of the three has a date type. Pick ISO 8601 strings and be explicit about the time zone, as covered in Unix timestamps and time zones.
A practical decision guide
- API responses and data exchange between programs: JSON. It is strict, universal, and easy to validate. If a payload will not parse, the common JSON syntax errors guide covers the usual causes, and the JSON formatter will show where it breaks.
- Configuration that humans edit and review: YAML, if you need comments and readability, with quoted strings wherever type confusion is possible. If you do not need comments, JSON avoids the entire class of problems above.
- Tabular exports, spreadsheets and bulk rows: CSV. Document the delimiter, the encoding and the quoting rules, and treat every column as text until you say otherwise.
- Nested data headed for a spreadsheet: convert deliberately with the JSON converter or the CSV tool, and check the flattened columns before anyone builds a report on them.
The rule of thumb is simple: let the shape of the data and the reader of the file choose the format. Machines exchanging nested data want JSON, people maintaining settings may want YAML, and anything that already lives in rows and columns belongs in CSV. When you must cross between them, expect to lose comments, types or structure, and verify the result rather than trusting it.