JSON vs YAML Comparison

JSON and YAML are both human-readable data serialization formats, but they serve slightly different niches. JSON prioritizes simplicity and unambiguous parsing, while YAML prioritizes human readability and expressiveness. Both can represent the same data structures, but their syntax and features differ significantly.

Syntax comparison:

JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "debug": true,
    "allowed_origins": ["example.com", "api.example.com"]
  }
}

YAML:

server:
  host: localhost
  port: 8080
  debug: true
  allowed_origins:
    - example.com
    - api.example.com

YAML uses indentation instead of braces and brackets, eliminates quotation marks for most strings, and uses - for array items. This makes it visually cleaner and easier to write by hand.

Key YAML features JSON lacks:

• Comments: YAML supports # comments on any line
• Multi-line strings: YAML offers | (literal block) and > (folded block) for multi-line text
• Anchors and aliases: YAML can reference and reuse values with &anchor and *alias
• Multiple documents: A single YAML file can contain multiple documents separated by ---
• Custom types: YAML supports tagged types like !!timestamp and custom type handlers

YAML's notorious gotchas:

YAML's flexibility creates well-known pitfalls. The value no is parsed as boolean false, not the string "no". The string 3.14.159 is parsed as a string, but 3.14 is a float. Country codes like NO (Norway) become false. Version strings like 1.0 become the number 1.0, losing the trailing zero. These implicit type conversions have caused production incidents, including the infamous "Norway problem" that has bitten many developers. The YAML 1.2 specification tightened these rules, but many parsers still use YAML 1.1 behavior.

Common mistakes developers make:

The most dangerous mistake is trusting YAML's implicit typing without quoting values that should remain strings. Always quote version numbers, country codes, and any value where the type matters. Another mistake is inconsistent indentation — YAML is whitespace-sensitive, and mixing tabs and spaces causes parse errors. Developers also underestimate YAML's complexity: the full YAML specification is significantly more complex than JSON's, leading to inconsistencies across parser implementations.

Best practices:

Use YAML for configuration files where human readability and comments are valuable (Kubernetes manifests, Docker Compose, CI/CD pipelines). Use JSON for data interchange, APIs, and machine-generated files. Every valid JSON document is also valid YAML (YAML is a superset of JSON), so you can always start with JSON and switch to YAML syntax if readability becomes a priority. When using YAML, always quote strings that could be misinterpreted as numbers or booleans.