YAML to JSON: converting configs without losing your mind

What a YAML to JSON conversion actually does

YAML and JSON describe the same shapes — maps, lists, strings, numbers, booleans and null — so the conversion is mostly a matter of re-serialising one syntax as the other. What changes is the surface: indentation becomes braces, comments disappear, anchors become copies, and multi-line strings collapse into `\n` escapes. Every one of those transformations is lossy in a way that matters, which is why the conversion step is worth doing deliberately rather than treating it as a formatting afterthought.

The practical reason to convert is that JSON is what the next tool wants. Kubernetes accepts YAML, but `kubectl`, jq pipelines, API calls and JavaScript all speak JSON more comfortably. Converting once, correctly, beats hand-editing two formats in parallel.

Multi-document YAML: the silent first-document problem

A YAML file can hold several documents separated by `---`. Most converters quietly return the first and throw the rest away — so a manifest bundle with a Deployment, a Service and a ConfigMap becomes one object with no warning. A correct conversion either emits an array of documents or asks you explicitly which one you want. If a converter offers no such control, it is losing data.

Errors should point at a line and column

YAML’s tolerance for whitespace is exactly why small mistakes are hard to find. Tabs are illegal for indentation, a missing colon turns a mapping into a string, and duplicate keys are accepted by some parsers and rejected by others. When a conversion fails, the only useful message names the line and column and shows the offending excerpt:

                spec:
  containers:
	- name: web      # tab used for indentation
error: line 3, column 0 — tabs cannot be used for indentation
              

Duplicate keys are the dangerous case: YAML parsers commonly keep the last value and say nothing. If `replicas: 3` appears twice, the JSON you get looks perfectly valid — and the wrong number.

Quoting rules that survive the trip

JSON is stricter about strings than YAML, so conversions add quotes around values that were bare. That is normal, but two YAML quirks cause real bugs: `yes`, `no`, `on` and `off` are booleans in YAML 1.1 but strings in JSON semantics, and leading-zero values such as zip codes and phone numbers lose their zero when treated as numbers. If a field must stay a string across the conversion, quote it in the source.

Run it locally, especially for cluster configs

Kubernetes manifests routinely carry credentials in `Secret` objects, connection strings in ConfigMaps and tokens in CI files. Pasting those into a web service hands them to a server you do not control. A browser-based converter does the parse and the serialise in the same tab you are reading, so nothing is transmitted — and a page that keeps working with the network cut off is proof of it rather than a promise.

A sensible workflow

1. Validate the YAML first and fix any reported line, column and excerpt.
2. Choose how multi-document files should be handled — array, or a specific document.
3. Convert with indentation that matches your codebase style (2 or 4 spaces), and sort keys if you are diffing output.
4. Keep YAML as the source of truth in git and treat the JSON as a generated artifact; comments live only in the YAML.