YAML vs JSON — Differences, Use Cases, and How to Convert

YAML and JSON are both data serialisation formats used extensively in software development. They can represent the same data but have different syntax, strengths, and use cases. Understanding when to use each will make you a better developer.

Key Differences

# Same data in JSON
{
  "name": "myapp",
  "version": "1.0.0",
  "ports": [80, 443],
  "debug": false
}

# Same data in YAML
name: myapp
version: "1.0.0"
ports:
  - 80
  - 443
debug: false

When to Use JSON

• REST APIs and web services — JSON is the standard
• JavaScript applications — native parsing with JSON.parse()
• When you need strict typing validation
• Data interchange between different languages and platforms

When to Use YAML

• Configuration files — Kubernetes, Docker Compose, GitHub Actions, Ansible
• When humans need to read and edit the file directly
• When you need comments (YAML supports # comments; JSON does not)
• CI/CD pipeline definitions

Common YAML Gotchas

# YAML is whitespace-sensitive — use spaces, not tabs!
# This is valid:
server:
  host: localhost
  port: 3000

# "Yes", "No", "True", "False" are treated as booleans in YAML!
country: NO  ← This becomes boolean false, not the string "NO"
# Fix: quote it
country: "NO"