JSON vs YAML: Picking the Right Config Format (Without Starting a War)

JSON is a data interchange format optimized for machines to read and write. It has strict syntax: every key must be quoted, commas are required between items, no comments allowed. YAML is a superset of JSON (all valid JSON is valid YAML) but adds human-friendly features: optional quotes, comments with #, multi-line strings, anchors for reusing values, and whitespace-based structure instead of brackets. JSON is faster to parse and has no ambiguity. YAML is easier to write by hand and maintain as a config file but has notoriously subtle parsing quirks, especially around data types.

Several reasons. First, whitespace is semantic — indentation changes meaning, and a misplaced space creates a bug that's hard to spot visually. Second, YAML auto-converts unquoted values to types in surprising ways: 'on', 'yes', 'true' all become boolean true, 'no' becomes false, '1.0' becomes a float. This caused notorious bugs in Ansible, Kubernetes, and CI/CD configs. Third, YAML supports multiple document types, references, and anchors that most parsers implement inconsistently. The Norway problem — country codes 'no' being parsed as false — has bitten multiple production systems. Always use a linter for YAML in CI pipelines.

Choose JSON for: API responses and requests (standard, every language can parse it), data stored in databases or files that programs read and write, schemas and OpenAPI specifications, package configuration files (package.json). Choose YAML for: CI/CD pipeline configs (GitHub Actions, GitLab CI), Kubernetes manifests, infrastructure as code (Ansible, Helm charts), application config files that developers edit frequently. YAML's comment support is genuinely valuable for configurations that need documentation inline. For configs that never change and aren't hand-edited, the format choice barely matters.