Two formats for the same data
YAML and JSON describe the same structures. YAML is what humans edit - Kubernetes manifests, CI pipelines, Docker Compose files, application configs - because it has comments and far less punctuation. JSON is what programs exchange, because its grammar is small enough to parse unambiguously.
Converting between them is routine: reading a CI config as JSON to process it in a script, converting an API response into YAML to check it into a repository, or simply flattening a deeply indented file to see its structure without counting spaces.
The YAML gotchas worth knowing
Indentation is structure, and tabs are forbidden. A single tab that your editor inserted invisibly will fail to parse, which is the single most common YAML error and the most annoying to spot.
Then there is the type coercion. Unquoted yes, no, on and off become booleans in YAML 1.1 parsers, which is why the country code NO turns into false and breaks an import. A version number like 1.10 becomes the float 1.1, silently losing the zero. Quoting values that must stay strings avoids all of it.
Converting to JSON is often the fastest way to see what your YAML actually says, because JSON has no such coercion - the ambiguity becomes visible the moment the values are rendered explicitly.
What is lost in conversion
Comments do not survive a trip through JSON, because JSON has no comment syntax. Converting a documented config to JSON and back strips every explanatory note, which is a real loss for a file other people maintain.
Anchors and aliases - YAML way of reusing a block - are expanded during conversion, so the output is correct but repetitive. Multi-line string styles collapse into ordinary strings with escaped newlines.
Frequently asked questions
- Is my configuration file uploaded?
- No. Conversion runs entirely in your browser, which matters because config files routinely contain internal hostnames and secret references.
- Why does my YAML fail to parse?
- Most often a tab character where spaces are required, since YAML forbids tabs for indentation. Inconsistent indentation depth and unquoted strings containing colons are the next most common causes.
- Why did NO become false?
- YAML 1.1 parsers coerce unquoted yes, no, on and off to booleans. Quote the value to keep it a string - a well-known problem for the Norway country code.
- Do comments survive conversion to JSON?
- No. JSON has no comment syntax, so comments are lost. Converting to JSON and back will strip the documentation from a config file.