JSON vs YAML vs TOML: Which One to Use

Three formats, one common mistake

JSON, YAML and TOML are not interchangeable. They look similar enough that engineers swap them by habit, then spend an afternoon explaining why the deploy broke.

JSON is for talking between machines. YAML is for humans writing configs. TOML is the no surprises middle ground that picked up steam when the other two showed their limits. Each one has a job, picking the right job is half the battle.

At a glance

JSON: the wire format

JSON is what data looks like on the network. Every API in the world speaks JSON, every browser parses it natively, every database imports and exports it.

{
  "name": "Maria",
  "age": 32,
  "skills": ["python", "sql"]
}

Strict syntax. No comments. No trailing commas. Strings always in double quotes. The strictness is the point: there is exactly one way to write each value, so two parsers always agree on what they see.

JSON is the right choice for:

• Machine to machine APIs.
• Data export and import.
• Storage formats that need to round trip cleanly.
• Anywhere a parser footprint matters (every language has JSON in the standard library).

JSON is the wrong choice for human edited files. The lack of comments alone makes it painful for any config file someone is going to read once a year. The JSON formatter on AldeaCode is useful when you receive a minified JSON blob and need to read it.

YAML: the human format that bites back

YAML lets humans write config without quoting strings or worrying about commas. Indentation defines structure, comments are allowed, and the file looks like a clean outline.

name: Maria
age: 32
skills:
  - python
  - sql

The cost is that YAML is not a simple format. The 1.2 spec is hundreds of pages, and most parsers implement different subsets. The “Norway problem” is the famous one: writing country: NO parses as country: false because YAML 1.1 treats NO as a boolean. There are dozens of similar gotchas.

YAML is the right choice for:

• Kubernetes manifests, where the ecosystem expects it.
• CI/CD pipelines (GitHub Actions, GitLab CI), same reason.
• Long human edited configs where comments and indentation help.

YAML is the wrong choice for:

• Anything where two parsers might disagree on the meaning.
• Data exchange between systems written in different languages.
• Files where a copy paste error can silently change a boolean to a string.

The single most useful YAML rule: pin the spec version, validate your file with the same parser as production, and never trust intuition about how a value parses.

TOML: the middle that does not surprise

TOML was designed by the GitHub founder out of frustration with YAML. The goal was simple: human readable, no implicit conversions, no whitespace sensitivity, one obvious way to write each thing.

name = "Maria"
age = 32
skills = ["python", "sql"]

[address]
city = "Madrid"
zip = "28001"

Sections ([address]) replace deep nesting. Strings are always quoted. Booleans are always lowercase true and false. There are no surprises because the spec deliberately removes all the surprises.

TOML is the right choice for:

• Tooling configs in the Rust and Python ecosystems (Cargo.toml, pyproject.toml).
• Files with mostly flat structure and a few sections.
• Anything where you want a YAML feel without YAML pitfalls.

TOML is the wrong choice for:

• Deeply nested data (the section syntax gets verbose fast).
• Anywhere the ecosystem has standardized on something else (Kubernetes is YAML, REST APIs are JSON, do not fight the convention).

How to pick in 30 seconds

If the file is read or written by code on both sides: JSON. If the file lives in a Kubernetes / CI / Ansible context: YAML, no choice. If the file is a tool config in Python or Rust land: TOML, the ecosystem expects it. If you are starting fresh with a human edited config and have a real choice: TOML by default, YAML if you need depth.

Converting between them

Most parsers can convert any of these to any other, with caveats. JSON to YAML is lossless. YAML to JSON loses comments. TOML to JSON is lossless. JSON to TOML loses cleanly only if the JSON is mostly flat.

When you receive a config and want to inspect it, paste it into the JSON formatter on AldeaCode after converting it. The find and replace tool is useful when you are migrating a YAML config to TOML and need to swap syntax patterns. Both run in your browser, no upload, no log.

The honest summary: JSON for machines, YAML where the ecosystem demands it, TOML when you have a real choice and want the format to stay out of your way. Picking the right one upfront saves more time than any parser improvement.