The short answer
All three describe the same thing - nested maps, lists, strings, numbers and booleans - so any of them can hold a config file. They differ in who is expected to write the file, what it can say beyond that common core, and how a parser can misread it.
| JSON | YAML | TOML | |
|---|---|---|---|
| Comments | No | Yes, # | Yes, # |
| null | Yes | Yes | No |
| Dates | Only as strings | Only as strings in YAML 1.2 | Native date and time types |
| Structure from | Braces and brackets | Indentation | [table] headers |
| Usual home | APIs, package.json, data files | Kubernetes, CI pipelines, Compose | Cargo.toml, pyproject.toml |
| Best when | A program writes it | The ecosystem expects it | A person edits it |
If nothing outside your project decides for you: JSON for data that programs exchange, TOML for a settings file people edit by hand, and YAML when the tool reading the file only speaks YAML. The rest of this guide is the detail behind that rule.
The same config in all three formats
Here is a small service config as JSON, followed by what the JSON, YAML and TOML converter writes for it in the other two formats.
{
"name": "api",
"port": 8080,
"debug": false,
"proxy": null,
"allowed_origins": ["https://example.com", "https://app.example.com"],
"database": { "host": "db.internal", "pool": 10 }
}name: api
port: 8080
debug: false
proxy: null
allowed_origins:
- https://example.com
- https://app.example.com
database:
host: db.internal
pool: 10
YAML drops the punctuation and lets indentation carry the nesting. It reads well, but the meaning of a line now depends on how far it is indented, and tabs are not allowed for indentation at all.
name = "api"
port = 8080
debug = false
allowed_origins = ["https://example.com", "https://app.example.com"]
[database]
host = "db.internal"
pool = 10
TOML keeps simple keys at the top and moves each nested map under a [table] header. Notice proxy is missing. TOML has no null, so the converter stops with this message unless you tell it to drop null values:
TOML has no null, so proxy cannot be written. Give it a value, remove it, or tick "Leave out null values".That is a real design difference, not a converter limitation. In TOML, "not set" is spelled by leaving the key out, and the program reading the file has to supply the default. If your code tells "absent" apart from "explicitly null", TOML cannot express that.
Where YAML bites: values that are not what they look like
YAML guesses types from unquoted text. Which guesses it makes depends on the YAML version, and the two versions in circulation disagree. Take this file:
country: NO
enabled: yes
version: 1.10
mode: 0755
port: 8080
Read as YAML 1.2, the current version and the one this site uses, it becomes:
{
"country": "NO",
"enabled": "yes",
"version": 1.1,
"mode": 755,
"port": 8080
}
Read as YAML 1.1, the same text gives country: false, enabled: true and mode: 493. YAML 1.1 treats yes, no, on, off, y and n as booleans, so the country code for Norway becomes false - the well-known "Norway problem". It also reads a leading zero as octal, so a file mode of 0755 becomes 493. YAML 1.2 dropped both rules, but PyYAML, still the most common YAML library in Python, implements 1.1.
The trap both versions share is version: 1.10, which is a float, so the trailing zero is gone and the value is 1.1. Version strings, ZIP and postal codes, phone numbers, Git commit hashes that happen to be all digits, and anything with a leading zero should be quoted. Quoting a string never hurts in YAML; leaving one unquoted occasionally changes what it means.
- Quote every value that is meant as text but could be read as a number, boolean, null or date.
- Indent with spaces only, and keep one indent width throughout the file.
- Run a linter such as yamllint in CI. Most YAML mistakes are valid YAML, so the program reading the file will not reject them.
- Anchors (
&name) and aliases (*name) let a file reuse a block, but most converters - including this one - expand them, so the reuse is lost once the file is converted.
Where JSON bites: comments and big numbers
JSON has no comments. A config file that cannot explain itself is the main reason teams move away from JSON for hand-edited settings. Paste one with a comment into the JSON formatter and validator or the converter and it is rejected:
{
// port
"port": 8080
}Comments are not allowed in JSON. Remove them, or read the input as YAMLSome tools accept "JSON with comments" (JSONC): tsconfig.json and VS Code settings are the best-known examples. That is a property of those tools, not of JSON. A standard JSON parser rejects the same file.
The second trap is numbers. JSON itself puts no limit on the size of a number, but JavaScript reads every number as a 64-bit float, which holds integers exactly only up to 9007199254740991 (Number.MAX_SAFE_INTEGER). One past that, and JSON.parse quietly returns a different value:
JSON.parse('{"id": 9007199254740993}').id
// 9007199254740992Nothing reports an error, the ID is just wrong. This is why APIs that use 64-bit IDs send them as strings as well - the Twitter API added id_str beside id for exactly this reason. The site's converter keeps such integers exact, but the code consuming your file may not.
JSON's strengths are the flip side of this strictness. There is one way to write each value, every language has a fast parser in its standard library, and JSON Schema can check a document's shape before your program trusts it.
Where TOML bites: deep nesting and no null
TOML is the most predictable of the three for a person to edit: strings are always quoted, there is no type guessing, and dates such as 2026-11-17T09:30:00Z are a real type rather than a string a program has to parse. Integers are 64-bit, and a value that would not fit is a parse error rather than a silent change.
The cost is structure. A TOML document is always a table at the top level, so a file whose root is a list cannot be written in TOML at all. Lists of objects use the [[name]] syntax, which repeats the header once per item:
title = "api"
[server]
host = "0.0.0.0"
port = 8080
[[routes]]
path = "/health"
auth = false
[[routes]]
path = "/orders"
auth = true
title: api
server:
host: '0.0.0.0'
port: 8080
routes:
- path: /health
auth: false
- path: /orders
auth: true
Two levels of this read fine. Five levels of nested tables, as in a Kubernetes manifest, become a wall of dotted headers that is harder to follow than the indented YAML. That is a large part of why infrastructure tooling settled on YAML and language package managers on TOML.
Note that YAML quotes 0.0.0.0 in the output above. Unquoted, it is still a string, but the converter quotes values that a reader could mistake for something else.
How to choose
- The file is produced and read by programs, or it is sent over HTTP: use JSON. It is the only one of the three that every runtime parses without a dependency.
- The file is settings a person edits, mostly flat or one or two levels deep: use TOML. Rust's Cargo and Python's
pyproject.tomlmade it the default for project metadata. - The tool that reads the file expects YAML - Kubernetes, GitHub Actions, GitLab CI, Docker Compose, Ansible: use YAML, quote ambiguous values, and lint it.
- The file already exists in one format: keep it. Every tool and script around it expects that format, and a conversion loses comments.
- Values must be able to be explicitly null: not TOML.
- The file needs comments: not JSON.
Converting between them
Conversion is safe for data but not for everything around it. Comments do not survive, because none of the three formats' data models include them. YAML anchors are expanded. Key order is kept by this site's converter, but many libraries sort or reorder keys, which makes the result noisy in a diff.
To check that a conversion kept the data, convert both files to JSON and compare them with JSON Compare, which ignores key order and formatting.
