Skip to content
Velloreth
Web Development 4 min read

JSON vs YAML vs TOML: Which Config Format Should You Use?

Compare JSON, YAML and TOML for config files and data: syntax, comments, readability and the mistakes to watch for. Same data in all three.

By

JSON vs YAML vs TOML: Which Config Format Should You Use?

If you have ever edited a configuration file, you have probably seen JSON, YAML, or TOML. All three are ways to write data that both humans and machines can read. They are not interchangeable in practice, because different tools expect different formats.

This article compares the three formats with the same data shown in each, so you can see the differences and choose the right one for your project.


Code editor with configuration files
JSON, YAML, and TOML are all ways to write configuration files, but they are not interchangeable.

The Same Data in All Three Formats

Here is the same small configuration expressed in each format:

JSON:

{
  "name": "my-app",
  "version": "1.0.0",
  "database": {
    "host": "localhost",
    "port": 5432
  },
  "debug": false
}

YAML:

name: my-app
version: "1.0.0"
database:
  host: localhost
  port: 5432
debug: false

TOML:

name = "my-app"
version = "1.0.0"

[database]
host = "localhost"
port = 5432

debug = false

Notice that JSON requires quotes around keys and string values, and uses commas between items. YAML uses indentation and colons. TOML uses = for assignment and groups related settings under [section] headers.


JSON: Strict and Universal

JSON (JavaScript Object Notation) is the most widely used data format on the web. It is strict:

  • All keys and string values must be in double quotes.
  • Strings must use double quotes.
  • Commas separate items in objects and arrays.
  • There are no comments.
  • Trailing commas are not allowed.

JSON is universal: nearly every programming language can read and write it. It is the default format for package.json, many API responses, and configuration files where machine readability matters more than human editing.

When to use JSON: When you need maximum compatibility, when the file is generated or read by machines more than humans, or when the tool requires it (for example, package.json).


YAML: Human-Friendly but Indentation-Sensitive

YAML (YAML Ain’t Markup Language) is designed to be easy for humans to read and write. It uses indentation to show structure, so there are no curly braces or closing tags.

YAML is more flexible than JSON: it allows comments, does not require quotes around most strings, and supports more complex data types. However, the indentation sensitivity means it is easy to make mistakes: a misplaced space can change the meaning of the document or cause a parse error.

When to use YAML: When the file is primarily edited by humans and the tool expects it (for example, Docker Compose, GitHub Actions workflows, Kubernetes manifests).


TOML: Minimal and Obvious

TOML (Tom’s Obvious, Minimal Language) aims to be a minimal configuration file format that is easy to read due to obvious semantics. It uses = for assignment and groups related settings under [section] headers.

TOML is less flexible than YAML but harder to misread: there are no significant indentation rules, and comments are supported. It is commonly used for language-specific configuration files.

When to use TOML: When the tool expects it (for example, Cargo.toml for Rust, pyproject.toml for Python).


Choosing the Right Format

In practice, you usually do not get to choose: the tool you are using expects a specific format.

  • package.json: JSON
  • Docker Compose: YAML
  • GitHub Actions: YAML
  • Cargo.toml: TOML
  • pyproject.toml: TOML
  • API responses: Usually JSON

If you are writing a new configuration file and have a choice, consider who will edit it. If it is mostly read by machines, JSON is a safe choice. If it is mostly edited by humans, YAML or TOML may be more readable — but be careful with indentation in YAML.


Questions and Answers

Q: What is JSON?

A: JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. It does not support comments.

Q: What is YAML?

A: YAML is a human-friendly, cross-language, Unicode-based data serialization language commonly used for configuration files.

Q: What is TOML?

A: TOML aims to be a minimal configuration file format that is easy to read due to obvious semantics and maps unambiguously to a hash table.

Q: Does JSON support comments?

A: No. The JSON grammar does not include a comment syntax.

Q: Which should I use?

A: It depends on your toolchain: JSON for package.json, YAML for Docker Compose and GitHub Actions, TOML for Cargo.toml and pyproject.toml.


Conclusion

JSON, YAML, and TOML are all ways to write structured data, but they are not interchangeable in practice. JSON is universal and strict; YAML is human-friendly but indentation-sensitive; TOML is minimal and obvious. In most cases, the tool you are using decides which format you use — so check the documentation before you start writing.


This article is informational and does not recommend one format over another for all use cases. Format support varies by tool; check current documentation before starting a project.

Frequently asked questions

What is JSON?
JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. It does not support comments.
What is YAML?
YAML is a human-friendly, cross-language, Unicode-based data serialization language commonly used for configuration files.
What is TOML?
TOML aims to be a minimal configuration file format that is easy to read due to obvious semantics, and maps unambiguously to a hash table.
Does JSON support comments?
No. The JSON grammar does not include a comment syntax.
Which should I use?
It depends on your toolchain: JSON for package.json, YAML for Docker Compose and GitHub Actions, TOML for Cargo.toml and pyproject.toml.