JSON vs YAML: The Format War

  • JSON (2001): Douglas Crockford—subset of JavaScript, strict syntax, APIs & data exchange
  • YAML (2001): 'YAML Ain't Markup Language'—human-friendly, indentation-based, config files
  • Fun fact: YAML is a superset of JSON—every valid JSON file is also valid YAML!

When to Use Which Format

  • JSON: APIs, package.json, tsconfig.json, browser storage, data interchange
  • YAML: Kubernetes, Docker Compose, GitHub Actions, Ansible, config files humans edit
  • Rule of thumb: Machines read JSON, humans read YAML
  • Comments: YAML supports # comments, JSON doesn't (use JSONC for comments)

YAML Gotchas That Break Deployments

  • Norway problem: 'NO' (country code) becomes boolean false—use quotes: 'NO'
  • Version strings: version: 3.10 becomes 3.1 (float)—use quotes: '3.10'
  • Octal numbers: 0777 is octal 511 in YAML 1.1, but string '0777' in 1.2
  • Timestamps: 2024-01-01 auto-parses as date—quote if you want string
  • Colon in values: 'key: value: more' breaks—use quotes or block scalar

DevOps Config Examples

  • Kubernetes: Deployments, Services, ConfigMaps—almost always YAML
  • Docker Compose: docker-compose.yml defines multi-container apps
  • GitHub Actions: .github/workflows/*.yml for CI/CD pipelines
  • Helm Charts: values.yaml for Kubernetes package configuration
  • Ansible: Playbooks and inventories in YAML

YAML Syntax Cheatsheet

  • Strings: plain, 'single quoted', or "double quoted"
  • Multiline: | (literal, keeps newlines) or > (folded, joins lines)
  • Lists: - item (dash + space) or [item1, item2] inline
  • Objects: key: value (colon + space) or {key: value} inline
  • Anchors: &name to define, *name to reference (DRY configs)
  • Merge: <<: *anchor to inherit properties from another object

JSON Syntax Refresher

  • Strings: Always double quotes "text" (never single quotes)
  • Numbers: 42, 3.14, 1e10 (no leading zeros except 0.x)
  • Booleans: true, false (lowercase only)
  • Null: null (not None, nil, or undefined)
  • No trailing commas: [1, 2, 3] not [1, 2, 3,]
  • No comments: Use JSONC (.jsonc) for commented config files

Common Conversion Scenarios

  • Copy API response (JSON) → paste into config file (YAML)
  • Debug Kubernetes: convert YAML manifest to JSON for jq processing
  • Migrate configs: old JSON configs → modern YAML format
  • Terraform: some providers accept either format
  • VS Code settings: settings.json to share as readable YAML snippets

Tools That Accept Both Formats

  • kubectl: kubectl apply -f works with .json or .yaml
  • Terraform: Accepts .tf.json as alternative to HCL
  • AWS CloudFormation: Templates can be JSON or YAML
  • Swagger/OpenAPI: API specs work in either format
  • ESLint: .eslintrc.json or .eslintrc.yml

Pro Tips

  • YAML indentation: Use 2 spaces consistently (never tabs!)
  • Validate before deploy: A single wrong indent can break everything
  • Use yamllint or jsonlint in your CI pipeline
  • VS Code: YAML extension catches errors as you type
  • When in doubt, quote it: Strings with special chars should be quoted