JSON vs YAML vs TOML: which format should you use?

The short answer

• JSON for data exchanged between programs: API requests and responses, stored documents, and anything generated by code.
• YAML for configuration that people read and edit often, especially in ecosystems that already use it, such as Kubernetes, Docker Compose, GitHub Actions, and Ansible.
• TOML for application and tool configuration with a clear, flat structure, such as Rust Cargo.toml and Python pyproject.toml.

All three describe the same building blocks: maps of keys to values, lists, strings, numbers, and booleans. The differences are in syntax, strictness, and how much the format tries to guess for you.

The same configuration in three formats

Here is a small service configuration written in each format. The data is identical; only the notation changes.

{
  "service": "orders",
  "port": 8080,
  "debug": false,
  "database": {
    "host": "db.internal",
    "pool_size": 10
  },
  "allowed_origins": ["https://app.example.com", "https://admin.example.com"]
}

service: orders
port: 8080
debug: false
database:
  host: db.internal
  pool_size: 10
allowed_origins:
  - https://app.example.com
  - https://admin.example.com

service = "orders"
port = 8080
debug = false
allowed_origins = ["https://app.example.com", "https://admin.example.com"]

[database]
host = "db.internal"
pool_size = 10

Side-by-side comparison

JSON: strict and universal

JSON is the most widely supported of the three. Every mainstream language can parse and generate it without extra dependencies, and its grammar is small enough that two parsers almost always agree on what a document means. That predictability is exactly why it dominates APIs.

The trade-off is that JSON is unforgiving for people. There are no comments, keys must be quoted, and a single trailing comma breaks the whole file. Long configuration files in JSON tend to accumulate small syntax errors when edited by hand, which is why many tools that use JSON for configuration quietly accept a commented variant instead.

YAML: readable, but it guesses

YAML is designed to be pleasant to read and write. Indentation shows structure, most strings need no quotes, and comments are supported. Since YAML 1.2, any valid JSON document is also valid YAML, so you can mix styles when convenient.

The price of that convenience is implicit typing. YAML decides whether an unquoted value is a string, number, boolean, or null, and the guesses are not always what you meant. Many tools still use YAML 1.1 rules, where yes, no, on, and off become booleans, so the country code NO for Norway turns into false. Version numbers like 1.10 become the number 1.1, and long numeric IDs can lose precision.

Indentation errors are the other common problem. Tabs are not allowed for indentation, and a key indented one level too deep or too shallow silently moves to a different parent instead of causing an error. Quoting any value that must stay a string, and converting suspicious files to JSON to see their real structure, prevents most YAML surprises.

TOML: explicit and flat

TOML, short for Tom’s Obvious Minimal Language, aims to be easy to read like YAML but unambiguous like JSON. Strings are always quoted, booleans are only true and false, and dates and times are a real data type rather than strings that a parser might or might not convert.

TOML organizes data with [section] headers and dotted keys, which works beautifully for configuration that is a few levels deep. It becomes awkward for deeply nested or highly dynamic data, such as large lists of objects with their own nested lists, where JSON or YAML stay more readable. Tooling support is also narrower than for JSON and YAML, although every major language has a solid parser.

How to choose

1. Is the file written by a program and read by another program? Use JSON.
2. Does your platform already define a format? Follow it. Kubernetes expects YAML, Cargo expects TOML, and fighting the ecosystem rarely pays off.
3. Do people edit the file by hand and need comments? Prefer YAML or TOML over plain JSON.
4. Is the structure deep, repetitive, or generated? JSON or YAML handle it better than TOML.
5. Do subtle typing mistakes carry real risk? TOML’s explicit types, or JSON validated with a JSON Schema, are the safest choices.

Validating each format

Syntax checks only tell you that a file can be parsed. To catch valid-but-wrong configuration, such as a missing required key or a port written as a string, describe the expected structure with a JSON Schema. Despite the name, a JSON Schema validates the parsed data, so it works for YAML and TOML files too once they are loaded.

Editors make this practical. The YAML extension for VS Code can apply schemas to files like Kubernetes manifests and GitHub Actions workflows, and TOML tooling such as Taplo supports schemas as well. In continuous integration, parse the file, validate it against the schema, and fail the build on errors, so broken configuration never reaches a running system.

Converting between formats

Because the data models overlap, converting is usually straightforward, with a few caveats. Comments are lost when converting YAML or TOML to JSON, because JSON cannot represent them. YAML anchors and aliases are expanded, so the JSON output can be larger than the source. TOML dates become strings in JSON. And YAML values that were guessed into booleans or numbers stay that way, so check the converted output for strings that changed type.

A practical workflow for teams is to keep human-edited configuration in YAML or TOML, validate it, and convert it to JSON at build time for programs that need JSON. The YAML to JSON Converter handles the YAML and JSON half of that workflow in your browser and shows syntax errors as you type.

Keep learning

• Common JSON errors and how to fix them
• JSONPath cheat sheet: syntax and examples
• JSON Formatter: Beautify, minify and validate JSON with syntax highlighting.
• JSON Schema Validator: Validate JSON payloads against JSON Schema standards with detailed error feedback.