JSON vs YAML: choosing a configuration format

Choose for the people editing it

JSON has a small grammar and predictable parsers. YAML is easier to scan in large configuration files but includes more syntax and type inference rules.

Where JSON fits best

JSON is a strong default for APIs, generated artifacts, package metadata and data exchanged across languages.

• Universal parser support
• Unambiguous braces and brackets
• Straightforward schema validation
• Reliable round trips

Where YAML fits best

YAML works well for configuration maintained by people: deployment manifests, automation workflows and settings with long block strings. Quote values that could be interpreted as dates or booleans, and validate after conversion.

Preserve a code and a number as different types

Use YAML to JSON with this fixture. The quoted postal code stays a string, replicas becomes a number and enabled becomes a boolean. The quotation marks are a data decision: removing them invites the YAML parser to interpret a value that may need to retain leading zeroes.

Convert the JSON result back with JSON to YAML, then parse that YAML again. Compare parsed values rather than exact indentation or quote style. XXF uses js-yaml for these conversions, so behavior should be checked against that parser and its version instead of assuming every YAML implementation resolves scalars identically.

postalCode: "00123"
replicas: 3
enabled: true

{
  "postalCode": "00123",
  "replicas": 3,
  "enabled": true
}

Expect comments and authoring choices to disappear

A YAML comment explains the author's intent but is not part of the JSON value model. Anchors, aliases, block-scalar style and preferred quoting also do not have direct JSON equivalents. Converting through a JavaScript value can resolve those structures rather than preserve their original spelling.

Keep the human-maintained YAML source when comments matter. Generate JSON as a separate artifact and validate it against the consuming service's schema. A parser accepts syntax; it does not confirm that a replicas field is within the application's allowed range or that a referenced environment variable exists.

• Quote identifiers and ambiguous text deliberately
• Keep comments in the authored YAML file
• Compare parsed values after a round trip
• Validate deployment rules separately from syntax