JSON, YAML, or TOML: Choosing a Config Format You Have to Hand-Edit

Quick answer

For a file you type into yourself, TOML is the safest pick, YAML is pleasant to read but easy to break, and JSON is strict and has no comments. This is about the person at the keyboard, not about machines exchanging data. That changes the ranking: what matters is whether you can leave notes, whether a stray comma ruins the file, and whether the parser quietly changes what you wrote.

JSON: strict, and no comments

JSON is defined by RFC 8259, and its grammar is short. That strictness hurts when you edit by hand:

• No comments. The only whitespace the grammar allows is space, tab, line feed and carriage return. A parser may accept extensions, so some tools tolerate comments, but you can't count on it.
• No trailing commas. Separators go only between members, so the comma after your last entry is a syntax error.
• Double quotes only, and the literals true, false and null must be lowercase.
• Leading zeros aren't allowed in numbers, so 007 is invalid.

{
  "port": 8080,
  "debug": true,
}

That trailing comma after true is all it takes to make the file unreadable to a strict parser. There's a subtler trap too: object names should be unique, and when they repeat, the RFC says the behavior of the receiving software is unpredictable. Some parsers keep the last value, others report an error.

JSON is fine for files machines write and read. It's a poor place to leave a note to yourself.

TOML: built for hand-editing

TOML describes itself as a minimal configuration format with obvious semantics, meant to map unambiguously to a hash table. In practice, most of what bites you in JSON and YAML simply doesn't happen.

# Where the server listens
port = 8080
debug = true
hosts = [
  "alpha",
  "beta", # trailing commas are fine in arrays
]

[database]
url = "postgres://localhost/app"

• # starts a comment that runs to the end of the line.
• Indentation is ignored, so you can't break the file by misaligning something.
• Defining the same key twice is invalid, which turns JSON's silent duplicate into a loud error.
• Arrays may end with a trailing comma. Inline tables ({ a = 1 }) may not, and they must stay on one line.
• Dates and times are real types: offset date-times, local dates and local times, plus 64-bit integers.

The catch is nesting. Deeply nested data turns into long [section.sub.sub] headers, which is why TOML suits settings better than large, tree-shaped documents.

YAML: readable until the indentation slips

YAML 1.2 reads the most like plain prose, and it supports # comments (preceded by whitespace) and anchors and aliases, so you can write a repeated block once. The price is that indentation is the structure.

server:
  port: 8080
  hosts:
    - alpha
    - beta

Indent hosts by one space too few and the meaning changes or the file fails to load. The spec forbids tabs in indentation, so a tab pasted from another editor is an error. Critics also note that a mis-indented line in a large file can go unnoticed, and a truncated file can still look valid because YAML has no closing marker. If you've hit the error message, our guide to YAML indentation errors walks through the usual causes.

The other YAML surprise is type coercion. Unquoted values are guessed. The YAML 1.2 core schema accepts only true, True, TRUE, false, False and FALSE as booleans, and any plain value that matches no pattern is a string. But unquoted Yes and No being read as booleans is behavior from older YAML 1.1, and parsers differ in which rules they follow. Wikipedia's YAML article lists this and version numbers read as floats among the known sources of errors. A country code like NO can turn into false.

country: NO        # may load as false in a YAML 1.1 parser
country: "NO"      # always a string
version: 1.10      # may load as the float 1.1
version: "1.10"    # a string

The fix: quote any value that must stay a string.

When to use it (and when to skip it)

• The tool dictates it. If the program you're configuring reads only one format, use that one. Most of the time, the choice is already made.
• You choose, and a person edits it: TOML. Comments, forgiving whitespace and loud duplicate-key errors cover most settings files.
• Machines write it, people mostly read it: JSON. It's strict, universal and easy to validate.
• Deeply nested data, or the tool requires it: YAML, with quoted strings and a linter.
• Just flat key-value pairs: consider a plain .env file instead. See env file syntax for the quoting rules.

How Carets fits in

Hand-editing config comes down to spotting mistakes early. Carets is a native notes and code editor for iPhone, iPad and Mac, and it gives code and config files syntax highlighting, so an unclosed quote or a stray character stands out before you save. It handles Markdown, plain text and code in one place, and your files stay plain text, portable and easy to move between devices. You can keep a project's config, notes and snippets together using files, projects and tags. For more on this workflow, read about editing config files and dotfiles on Mac and iOS.

Download Carets for iPhone, iPad and Mac on the App Store.

Frequently Asked Questions

Does JSON support comments?

Not in the standard. RFC 8259's grammar allows only space, tab, line feed and carriage return as whitespace, though it lets a parser accept extensions, so some tools tolerate comments. Don't rely on it in files other people or tools will read.

Is YAML a superset of JSON?

YAML 1.2 was designed to be, and its spec names that as the primary focus of the revision. Older 1.1 parsers aren't strictly compatible, and in practice tools differ, so test your own parser before relying on it.

Why does TOML reject my inline table?

Inline tables must stay on a single line and, unlike arrays, don't allow a trailing comma. Remove the comma, or switch to a regular [table] section.

Which format should I pick for a file I edit by hand?

If the tool allows a choice, TOML suits most settings files because it has comments and ignores indentation. Use YAML when the tool requires it or the data is deeply nested, and JSON when machines write the file more than you do.