From JSON to YAML Without Breaking Your Config: A Practical Guide
By the Super Simple Digital Tools Team · Updated June 2026
JSON and YAML are two ways of writing the same thing. Under the hood both encode a tree of mappings (key-value pairs), sequences (lists), and scalar values like strings, numbers, booleans and null. That shared model is why conversion is reliable: there is no information in well-formed JSON that YAML cannot represent. What changes is the surface syntax. JSON marks structure with braces, brackets, commas and quotes; YAML marks it with indentation and dashes. Strip the punctuation, indent consistently, and a dense JSON object becomes a YAML file you can scan top to bottom like a checklist.
So why bother, if a system accepts both? Because YAML won the configuration ecosystem. Kubernetes manifests, Helm charts, Docker Compose, GitHub Actions and GitLab CI pipelines, and Ansible playbooks are all written in YAML by convention. The big reasons are human ones: YAML files have less syntactic noise, nest more readably, and crucially support comments, something JSON flatly refuses. When a deployment file is edited by people during incidents, being able to annotate why a value is set the way it is matters more than raw parsing speed. JSON still dominates APIs and machine-to-machine data exchange, which is exactly where the conversion need arises.
The single biggest gotcha in YAML is indentation, because indentation is not cosmetic, it is the structure. There are no closing braces to fall back on, so one extra or missing space can silently move a key to the wrong nesting level or invalidate the file. The cardinal rule: never use tabs. The YAML spec forbids tab characters for indentation, and mixing tabs with spaces, often introduced by copy-pasting from a terminal or documentation, is one of the fastest ways to produce a file that looks fine but won't parse. Pick two spaces per level and stay consistent throughout.
The second classic trap is implicit typing. YAML tries to infer whether a bare value is a string, number or boolean. Under the still-common YAML 1.1 rules, words like yes, no, on, off, true and false (in many capitalisations) all become booleans, which is how the Norway problem got its name: the country code NO parses as the boolean false. Leading-zero values like 0755 or version-looking strings can also be coerced unexpectedly. The fix is simple and is why a good converter quotes proactively: wrap any value whose textual meaning matters in quotes so the parser treats it as a literal string.
A sensible workflow, then, is convert, scan, validate. Convert the JSON to get clean block-style YAML. Scan the output for any values that should be strings but were left bare, and confirm the indentation depth matches where the snippet will live in a larger file. Then run it through a YAML linter or the target tool's dry-run mode before committing. Because the conversion is lossless, anything that breaks afterwards is almost always one of the two YAML-specific issues, indentation or implicit typing, not the data itself.
- Use two spaces per indentation level and never tabs; configure your editor to insert spaces on Tab so pasted YAML stays parseable.
- After converting, check that values like NO, yes, off, or numbers with leading zeros are quoted if you meant them as strings, to dodge YAML's implicit-typing traps.
- When pasting converted YAML into a Kubernetes or CI file, re-indent the whole block so its top level lines up with its parent key rather than the file's left margin.
- Run the output through a YAML linter or your tool's dry-run (for example kubectl apply --dry-run) before committing, since YAML errors often hide in invisible whitespace.