YAML and JSON: Two Faces of Configuration
YAML and JSON are the two dominant formats for configuration files, data serialization, and infrastructure-as-code in modern software. JSON (JavaScript Object Notation) grew out of JavaScript object literals and is prized for its strict syntax, universal parser support, and unambiguous structure. YAML (YAML Ain't Markup Language) evolved as a more human-friendly alternative, supporting comments, multi-line strings, anchors, and a relaxed indentation-based structure.
The two formats are surprisingly compatible at the data model level. Both represent the same primitive types — null, boolean, integer, float, string, array, and object — and most YAML parsers can produce JSON-compatible output directly. This compatibility is what makes conversion between them a common and useful operation: developers often write configuration in YAML for readability and convert to JSON for tools that require it, or extract JSON from an API response and reformat it as YAML for documentation.
Despite their semantic overlap, the formats have different trade-offs that influence which to choose. JSON is stricter and more portable, with consistent parsing across every language and tool. YAML is more expressive and easier to read but has a more complex specification, more parser variation, and subtle pitfalls around type coercion that can cause security and correctness issues if you are not careful.
- JSON: strict syntax, universal support, no comments
- YAML: human-friendly, supports comments and multi-line strings
- Both share the same primitive data model
- Conversion is lossless in most cases, with caveats around types
Syntax Differences Every Developer Should Know
JSON requires double-quoted strings, mandates commas between elements, and disallows trailing commas and comments. YAML, by contrast, allows unquoted strings in most contexts, uses indentation rather than braces to denote structure, and supports comments with `#`. These differences make YAML significantly more readable for humans but also introduce parsing complexity.
One of the most notorious YAML pitfalls is implicit type coercion. The string `no` is parsed as a boolean false, `null` becomes null, `3.14` becomes a float, and `0123` may be interpreted as an octal number depending on the parser version. This implicit coercion has caused production incidents — the canonical example being a developer setting `enabled: no` expecting a string and getting a boolean that changed application behavior. The fix is to quote strings explicitly when their literal value matters.
YAML anchors (`&anchor`) and aliases (`*alias`) let you reference a value defined elsewhere in the document, which is powerful for DRY configuration but breaks JSON compatibility since JSON has no equivalent. When converting YAML with anchors to JSON, the anchors must be resolved (expanded inline) during conversion, which most converters handle automatically. The reverse direction — JSON to YAML — is always safe since JSON has no features YAML cannot represent.
- JSON requires double quotes; YAML allows unquoted strings
- YAML supports comments; JSON does not
- YAML implicitly coerces unquoted strings like no, true, null, 0123
- YAML anchors and aliases have no JSON equivalent and must be resolved
- Multi-line strings: YAML has |, >, and folded forms; JSON requires \n escapes
Converting YAML to JSON
Converting YAML to JSON is the more common direction, since YAML is preferred for authoring and JSON is preferred for tooling. Most modern programming languages have libraries that parse YAML into native data structures, which can then be serialized as JSON with a single call. In JavaScript, the `js-yaml` package parses YAML and `JSON.stringify` produces JSON; in Python, `yaml.safe_load` and `json.dumps` do the same.
Always use a well-tested parser rather than rolling your own conversion. YAML's specification is large and includes features (anchors, tags, complex keys, flow style, block style) that are easy to misinterpret. A mature parser handles these correctly and produces a normalized data structure that serializes cleanly to JSON. Avoid parsers that have not been updated recently, as older versions may have security vulnerabilities around arbitrary object instantiation.
When converting, be aware of features that do not survive the round trip. Comments in the original YAML are lost when converting to JSON, since JSON has no comment syntax. Custom YAML tags (like `!!timestamp`) may be parsed into native types (Date objects) and serialized back as ISO strings rather than the original form. If round-trip fidelity matters, store the original YAML separately and treat the JSON as a derived artifact.
- Use `js-yaml` in JavaScript, `PyYAML` in Python, or equivalent libraries
- Always prefer safe_load variants to avoid arbitrary object instantiation
- Comments are lost when converting YAML to JSON
- Custom tags may be normalized to JSON-native types during conversion
Converting JSON to YAML
Converting JSON to YAML is generally simpler than the reverse, since JSON's strict syntax and limited feature set translate cleanly into YAML. Most YAML emitters accept a native data structure (which you obtain by parsing the JSON) and produce YAML output. The main decisions are about formatting: indentation width, line width for wrapping, and whether to use flow style (inline braces) or block style (indented).
A common reason to convert JSON to YAML is to make a configuration file more readable and editable. JSON config files become significantly more maintainable when converted to YAML, especially when you add comments explaining non-obvious values. Many tools — Kubernetes, Docker Compose, Ansible, GitHub Actions — use YAML precisely because it is human-friendly for configuration at scale.
When emitting YAML from JSON, configure the emitter to use block style (not flow style) for maximum readability, set a consistent indentation width (typically 2 spaces), and disable line wrapping or set a generous width to avoid awkward mid-value breaks. For strings containing newlines, prefer the literal block scalar (`|`) over escaped ` ` sequences, which makes multi-line content far easier to read in the YAML output.
- JSON-to-YAML is generally safe and lossless
- Choose block style and 2-space indentation for readability
- Use literal block scalars (|) for multi-line strings
- Add comments after conversion to document non-obvious values
Security Considerations with YAML
YAML has historically had security issues related to arbitrary object instantiation. Some YAML parsers, by default, support tags that instruct the parser to instantiate arbitrary objects — a feature that can be exploited to achieve remote code execution if the parser processes untrusted YAML. The classic example is the Python `yaml.load` function (without the `safe` variant), which has been the basis of multiple CVEs.
The fix is straightforward: always use the safe loading variant of your YAML library. In Python, use `yaml.safe_load` instead of `yaml.load`. In JavaScript, `js-yaml`'s `load` function uses a safe schema by default in modern versions, but you should verify the schema configuration when integrating with new code. Never feed user-supplied YAML into a parser configured for arbitrary object instantiation.
JSON has no equivalent feature — it produces only primitive types, arrays, and objects, with no mechanism for code execution during parsing. This makes JSON safer for untrusted input. If you must accept YAML from untrusted sources, consider parsing it with a restricted schema or converting it to JSON via a hardened parser before processing. For internal configuration where you control the source, YAML's expressiveness outweighs the security concern as long as you use safe parsing.
- Some YAML parsers support tags that instantiate arbitrary objects
- Always use safe_load variants when handling untrusted YAML
- JSON has no equivalent code-execution risk during parsing
- For untrusted input, prefer JSON or use a restricted YAML schema
Best Practices for Configuration Management
Choosing between YAML and JSON — and converting between them — is part of a broader configuration management strategy. Start by establishing a single source of truth for each configuration concern, and derive other formats from it rather than maintaining parallel copies. If your team authors in YAML but a tool requires JSON, generate the JSON from the YAML as a build step rather than editing both files by hand.
Validate configuration against a schema. JSON Schema works for both formats and lets you enforce required fields, type constraints, and value ranges. Validation catches typos and missing fields before they reach production, and it makes configuration errors immediately understandable rather than manifesting as runtime exceptions deep in your code. Tools like ajv (JavaScript), jsonschema (Python), and cloud-specific validators make this easy to integrate.
Finally, treat configuration as code. Store it in version control, review changes through pull requests, and test configuration updates in a staging environment before deploying to production. Automated diffing of generated JSON can surface unexpected changes (a subtle type coercion, an accidentally-removed key) before they cause incidents. With these practices, the choice between YAML and JSON becomes a matter of authoring preference rather than a source of operational risk.
- Establish a single source of truth and derive other formats from it
- Validate configuration against a JSON Schema
- Store configuration in version control and review changes
- Automate diffs of generated JSON to catch unexpected changes
- Test configuration updates in staging before production