YAML vs JSON: Which Format for Config and CI

"YAML or JSON?" is really three questions: who edits the file, who reads it, and what breaks when a value is misread. YAML optimizes for human editing — comments, anchors, no quote noise — and pays with a coercion layer that has caused real outages. JSON optimizes for machines and interchange and pays in unreadability at scale. Most real-world answers are "both, in different files in the same repo"; the skill is knowing which file gets which, and how to convert without losing something silently.

Where YAML wins

• Human-edited config with review workflows. Kubernetes manifests, Docker Compose, GitHub Actions, GitLab CI, Ansible. Comments are load-bearing in review — # bump with app version next to a field survives redeploys; a Slack message does not.
• Deep, repetitive structures. Anchors and aliases (&base / *base) deduplicate near-identical blocks; block scalars (|, >) keep long strings and scripts readable without \n escapes.
• Files humans diff by eye. Indentation shows structure without punctuation; a reviewer sees a changed block, not a changed line of escaped text.

Where JSON wins

• Anything crossing a process boundary. REST and GraphQL payloads, queues, structured logs. Every language parses JSON natively; YAML needs a dependency and a choice among spec versions.
• Machine-generated files. Lockfiles, exports, codegen inputs. No comment support is a feature here — reformatting tools cannot destroy information.
• Predictable typing. Exactly four scalar types. No parser turns NO into false or 010 into 8.
• Schema tooling. JSON Schema is the industry's most mature validation story, and OpenAPI — however it is serialized — is defined in JSON terms.

The YAML traps that actually break production

1. The Norway problem. Under YAML 1.1 (still the default in PyYAML and several SDKs), unquoted country: NO parses as false. So do on, off, yes, and no — a flag written as enabled: on is true in one library and the string "on" in another. Rule of thumb: when a value reads as text, quote it — country: "NO", not country: NO.
2. Octal and sexagesimal surprises. mode: 010 is the number 8 in YAML 1.1; 1:30 can parse as 90 (sexagesimal) in some parsers. File permissions and durations are the classic victims.
3. Version numbers are not strings. version: 1.10 is the number 1.1. Unquoted versions, build numbers, and ZIP codes get silently reinterpreted.
4. Indentation is semantics. Tabs are illegal; a two-space shift changes nesting. Diff tools that "fix" whitespace can turn one document into another.
5. Duplicate keys are undefined behavior. Parsers take the last, the first, or throw. A merged config with retries: 3 twice can pass review and flip behavior after a library upgrade.

Decision table by use case

The conversion workflow that catches surprises

1. Convert YAML → JSON in the YAML to JSON Converter and read the output with fresh eyes: every false that used to be a country code, every 8 that used to be 010, shows up here.
2. Convert the JSON back → YAML and diff against the original. Differences in formatting are fine; a changed value means a coercion bug.
3. Quote every flagged scalar in the source and repeat. A stable round-trip is the contract you want before the file ships.

For tabular data that feeds a JSON API, the same discipline applies: the CSV to JSON Converter handles header-row and separator decisions, and the same round-trip check catches encoding and delimiter surprises before they reach the pipeline.

What about TOML, HCL, and XML?

They occupy real niches: TOML (Cargo, pyproject) is deliberately unambiguous and excellent for small human-edited configs; XML survives in SOAP ecosystems and document formats; HCL is Terraform's domain. The same review question applies to each of them: if a generated file can drift from its source, the conversion — not the format — is what needs a test.