JSON, YAML, CSV, and TOML: When to Use Each Data Format

Software spends a surprising amount of its life just moving structured data around: an API returns JSON, a config file is written in YAML or TOML, a report is exported as CSV, a spreadsheet wants tabular rows. These formats are not interchangeable — each was designed for a particular job, and using the wrong one creates friction. Knowing the strengths of each makes you faster and saves you from a category of frustrating bugs.

JSON: the lingua franca of APIs

JSON (JavaScript Object Notation) is the default for data exchange between systems, especially web APIs. It represents nested objects and arrays cleanly, every programming language can parse it, and its rules are strict enough to be unambiguous. That strictness is also its main friction for humans: no comments are allowed, every string needs double quotes, and a single trailing comma makes the whole document invalid. JSON is excellent for machine-to-machine communication and data storage; it is merely tolerable for files humans have to edit by hand.

YAML: configuration humans edit

YAML was designed to be readable and writable by people. It uses indentation instead of braces, supports comments, and drops most of the punctuation that makes JSON noisy. This makes it popular for configuration in tools like CI pipelines and container orchestration. Its strength is also its danger: because structure is defined by indentation, a single misplaced space can silently change the meaning of your file or break it entirely. YAML also has surprising type-coercion quirks (the classic example: the word "no" being read as the boolean false). Use YAML for human-edited configuration, but validate it.

TOML: configuration that stays unambiguous

TOML (Tom's Obvious Minimal Language) aims for YAML's readability without YAML's ambiguity. It uses explicit, INI-like sections and clear key-value pairs, supports comments, and has unambiguous typing. It is less prone to the silent indentation mistakes that plague YAML, which is why a number of modern tools have adopted it for their config files. It is excellent for flat-to-moderately-nested configuration; deeply nested data structures become more awkward in TOML than in JSON or YAML.

CSV: flat, tabular data

CSV (Comma-Separated Values) is the simplest of the four and the right answer for one specific shape of data: flat tables of rows and columns, like a spreadsheet export. It is universally understood by spreadsheet software, databases, and data tools. Its limitation is that it has no concept of nesting — you cannot represent an object-within-an-object cleanly. It also has real-world messiness around quoting, commas inside values, and inconsistent line endings. Use CSV for tabular data destined for spreadsheets or simple import/export; do not try to force hierarchical data into it.

Converting between them

Conversions are common and mostly straightforward, with one thing to watch: structural mismatch. JSON, YAML, and TOML can all represent nested data, so converting among them is usually clean. CSV is flat, so converting nested JSON to CSV requires flattening — a nested key like user.address.city typically becomes a column header using dot notation. Going the other way, from CSV to JSON, gives you a flat array of objects. Understanding this is the key to not being surprised by the output.

Quick rule of thumb:

• API responses and data interchange → JSON.


• Human-edited config in pipelines and orchestration → YAML (and validate it).


• Human-edited config you want to stay unambiguous → TOML.


• Flat tabular data for spreadsheets → CSV.

Converting between JSON, CSV, YAML, and TOML is quick, bidirectional work with the right tool — validating the input and flattening or expanding the structure as needed. When you only need to tidy and check a single format — pretty-printing minified JSON, or catching a syntax error in a config file — a formatter is the faster route. And when the source or destination is an actual spreadsheet file, that is its own short conversion.

Done in the browser, none of it requires your data files to leave your machine — which matters when the "data" is a customer export or anything you'd rather not upload. I built a small client-side converter for exactly this at boxtool.io/data-converter: JSON/YAML/CSV/TOML both ways, everything runs locally in the tab. It's free — I mention it only because "runs locally" is the whole point of the article.