JSON vs YAML vs XML: Which Configuration Format Wins?

The Same Config in All Three Formats

Here is a database configuration expressed in JSON, YAML, and TOML. Read all three and notice what your brain finds easiest, that instinct usually points to the right answer for your use case.

1// JSON — no comments allowed, verbose punctuation
2{
3  "database": {
4    "host": "localhost",
5    "port": 5432,
6    "name": "production_db",
7    "ssl": true,
8    "pool": {
9      "min": 2,
10      "max": 10,
11      "timeout": 30000
12    }
13  }
14}

1# YAML — comments work, but whitespace is significant
2# This is the production database config
3database:
4  host: localhost
5  port: 5432           # PostgreSQL default
6  name: production_db
7  ssl: true
8  pool:
9    min: 2
10    max: 10
11    timeout: 30000     # 30 seconds in ms

1# TOML — explicit types, comments, no significant whitespace
2# Production database configuration
3 
4[database]
5host = "localhost"
6port = 5432           # PostgreSQL default
7name = "production_db"
8ssl = true
9 
10[database.pool]
11min = 2
12max = 10
13timeout = 30_000      # Underscores allowed in numbers for readability

JSON: Fast, Strict, Commentless

JSON is defined byIETF RFC 8259. Its rules are intentionally minimal: six data types (string, number, boolean, null, array, object), no comments, strict quoting requirements.

The no-comments restriction is a deliberate design choice. Douglas Crockford, who formalised JSON, removed comment support because comments were being used to embed parser directives, turning a data format into a config language. For data interchange (API responses, serialised state), this strictness is a feature. For configuration files, it is a constant frustration.

Where JSON excels: speed. JSON.parse() is a native browser function compiled directly into the JavaScript engine. It is 10–15× faster than js-yaml and comparable to the fastest compiled-language YAML parsers.

YAML: Readable but Treacherous

YAML's design goal was human readability above all else. It achieves this, a YAML config file is often easier to read than its JSON equivalent, especially for nested structures and multi-line strings.

But YAML hides serious parsing traps.

The Norway Problem: YAML's Famous Boolean Trap

In YAML 1.1, the following strings are all parsed as boolean values without quotes:

1# YAML 1.1 boolean traps (22 values total)
2true:  true, True, TRUE, yes, Yes, YES, on, On, ON
3false: false, False, FALSE, no, No, NO, off, Off, OFF
4 
5# Real-world consequence: country codes in a config
6country_code: NO   # → parsed as false (Norway's ISO code!)
7feature_flag: yes  # → parsed as true (you wanted the string "yes")
8 
9# Fix: always quote strings that might match boolean patterns
10country_code: "NO"
11feature_flag: "yes"

YAML 1.2 fixed this, only true and false are boolean. But most parsers (including js-yaml below version 4.0, PyYAML, and Go's gopkg.in/yaml.v2) still implement YAML 1.1. Check your parser version before trusting unquoted strings.

Tabs Are Illegal in YAML

YAML prohibits tab characters for indentation. Only spaces are valid. Many code editors default to tabs for some file types, this causes silent parse failures in YAML files opened and edited by tab-defaulting editors.

1# WRONG — tab character for indentation causes a parse error
2database:
3	host: localhost   # ← tab here — INVALID YAML
4 
5# Correct — spaces only
6database:
7  host: localhost   # ← two spaces — valid

Implicit Type Coercion Surprises

YAML infers types from unquoted values. This causes data corruption in unexpected places:

1# Type coercion surprises in YAML
2version: 1.0       # → float 1.0 (not string "1.0")
3phone: 07911123456 # → int 7911123456 (leading zero stripped!)
4hex_color: 0xFF    # → int 255 (hex parsed!)
5date: 2026-07-02   # → datetime object (not string!)
6null_val:          # → null (empty value is null)
7 
8# These all need quoting to remain strings:
9version: "1.0"
10phone: "07911123456"
11hex_color: "0xFF"
12date: "2026-07-02"

TOML: The Underrated Alternative

TOML (Tom's Obvious Minimal Language) was created by Tom Preston-Werner (GitHub co-founder) specifically to be a configuration format without YAML's ambiguity problems.

TOML's type system is explicit: strings require quotes, integers and floats are distinguished, dates are a native type, and there is no implicit coercion. A TOML file never silently converts NO to false.

It is now the default configuration format for several major ecosystems:

• Rust: Cargo.toml (every Rust project)
• Python: pyproject.toml (PEP 517/518 packaging standard)
• Hugo: config.toml (static site generator)
• Zola, Nix, uv, Rye: all default to TOML

Full Format Comparison

Edge Cases That Break Each Format

YAML Anchors: Powerful but Confusing

YAML supports anchors and aliases for reusing values across a file. This is useful for large configs but a debugging nightmare when overused:

1# YAML anchor — define once
2defaults: &defaults
3  retries: 3
4  timeout: 5000
5 
6# YAML alias — reuse the anchor (merges the values)
7production:
8  <<: *defaults    # Inherits retries: 3 and timeout: 5000
9  host: prod.example.com
10 
11staging:
12  <<: *defaults
13  host: staging.example.com
14  timeout: 10000   # Override just this value

Anchors work well when used sparingly. Files with anchors of anchors of anchors become very hard to debug. No equivalent exists in JSON or TOML.

JSON Trailing Commas: Still Broken in 2026

Standard JSON does not allow trailing commas. This is an endless source of parse errors:

1// INVALID JSON — trailing comma after last element
2{
3  "name": "FileMint",
4  "version": "2.0",   // ← trailing comma — JSON.parse() throws
5}
6 
7// VALID JSON — no trailing comma
8{
9  "name": "FileMint",
10  "version": "2.0"
11}
12 
13// Note: JSONC (JSON with Comments) and JSON5 allow trailing commas
14// Use these for config files read by tools that support them (VS Code, ESLint)

YAML Multi-line String Modes

YAML has two multi-line string operators with different newline handling:| (literal, preserves newlines) and> (folded, collapses newlines to spaces). Using the wrong one produces unexpected whitespace in parsed strings:

1# Literal block (|) — preserves every newline
2message: |
3  Line one
4  Line two
5# → "Line one
6Line two
7"
8 
9# Folded block (>) — newlines become spaces (except blank lines)
10message: >
11  Line one
12  Line two
13# → "Line one Line two
14"
15 
16# Folded is for prose. Literal is for code, SQL, or anything line-sensitive.

My Recommendation by Use Case

When you must use YAML: always quote strings that could match boolean patterns. Set your editor to show whitespace characters. Use a YAML linter (yamllint) in your CI pipeline. These three habits eliminate the class of bugs that cost me 40 minutes in production.

For API-level format decisions (not configuration files), our XML vs JSON comparison covers the performance and schema validation tradeoffs that apply when the format is used in network communication rather than local config files. If you need to convert between formats, our YAML to JSON converter runs entirely in your browser.