JSON vs CSV vs YAML: Which Data Format Should You Use?

JSON, CSV, and YAML show up constantly in APIs, configuration files, databases, and spreadsheets. They are all ways to represent structured data, but they are not interchangeable. Here is what each format is built for, where each one falls short, and how to choose between them.

CSV: Simple Tables, Nothing More

CSV (Comma-Separated Values) is the plainest format of the three. It represents a flat table: rows and columns, like a spreadsheet stripped of all formatting.

name,age,city
Alice,30,London
Bob,25,New York

CSV's strength is its simplicity. Every spreadsheet application opens it. Every database can import it. Every programming language has a CSV parser built in or available as a one-line install. The format has virtually zero overhead: no brackets, no repeated keys on every row, no structural punctuation.

A CSV file containing 10,000 rows of customer data is dramatically smaller than the same data in JSON format, because JSON repeats every field name on every row.

CSV's weakness is equally obvious: it only handles flat data. You cannot represent a nested structure (a user with an array of orders, for example) without either flattening it awkwardly into multiple columns or splitting it into multiple files. There is also no standard way to specify data types. A field containing the number 30 and a field containing the text "30" look identical in a CSV file.

Use CSV for: tabular data, reports, exports, datasets, anything you would put in a spreadsheet, and any data that needs to be imported into a database or analysed in Excel.

JSON: The Web's Native Language

JSON (JavaScript Object Notation) represents nested, structured data as key-value pairs, arrays, and objects.

{
  "name": "Alice",
  "age": 30,
  "orders": [
    { "id": 1, "item": "book" },
    { "id": 2, "item": "pen" }
  ]
}

JSON can represent any data structure. It handles nesting naturally, preserves data types (numbers, strings, booleans, null, arrays, and objects are all distinct), and has native support in every programming language in common use today. It is the default format for REST APIs, browser local storage, and configuration in JavaScript and TypeScript projects.

The trade-off is verbosity. All those curly braces, quotation marks, and commas add up. A large JSON file with many records is significantly larger than the equivalent CSV. This matters less than it used to as bandwidth is cheap, but it is worth keeping in mind for very large datasets or high-frequency API calls.

JSON also has no support for comments. You cannot add a note explaining why a configuration value is set a particular way. This makes JSON awkward for configuration files that humans write and maintain over time.

Use JSON for: APIs, web applications, any nested or complex data structure, cross-language data exchange, and browser-based storage.

YAML: Configuration Files Done Right

YAML (YAML Ain't Markup Language) is a superset of JSON that strips out most of the punctuation. The same data from the JSON example above in YAML:

name: Alice
age: 30
orders:
  - id: 1
    item: book
  - id: 2
    item: pen

YAML is dramatically more readable than JSON for humans. The indentation-based structure is intuitive. Key-value pairs do not need quotation marks around simple strings. Most importantly, YAML supports comments: a crucial feature for configuration files where you want to explain why a value is set the way it is, not just what it is.

This is why YAML became the standard format for configuration in modern infrastructure tools: Docker Compose, Kubernetes manifests, GitHub Actions workflows, CI/CD pipelines, and Ansible playbooks all use YAML. When a file is written by a human and read by a human dozens of times over its lifetime, YAML's readability pays off.

The catch is that YAML's flexibility is also its weakness. Its parsing rules have subtle edge cases. The infamous "Norway problem" refers to the value NO being parsed as a boolean false by some parsers, because YAML has shorthand boolean representations. Indentation errors cause silent failures or unexpected behaviour. For machine-to-machine data exchange where no human ever reads the file, these quirks make YAML a poor choice compared to JSON.

Use YAML for: configuration files, infrastructure-as-code, any file that humans write and maintain regularly.

Quick Decision Guide

Common Conversion Scenarios

A few situations where you will regularly need to convert between these formats:

• Exporting API data to a spreadsheet: convert JSON to CSV so the data opens correctly in Excel or Google Sheets.
• Importing a CSV into an application: convert CSV to JSON to use the data in a web application or API.
• Migrating configuration files: convert JSON config to YAML when moving to a tool that expects YAML, or vice versa.
• Debugging API responses: paste a JSON response into a formatter to make it readable, then convert to CSV to compare rows of data.

Convert Between Formats Free

Need to switch between these formats? Convert instantly in your browser with no software to install and no account required.