The implicit-typing minefield, mapped
Most YAML→JSON surprises trace to bare scalars that YAML types for you:
| You wrote | YAML 1.1 reads | Keep it a string with |
|---|---|---|
country: NO | false | country: "NO" |
version: 1.10 | 1.1 (float) | version: "1.10" |
mode: 0755 | 493 (octal) | mode: "0755" |
when: 2026-06-12 | date object | when: "2026-06-12" |
id: 1e2 | 100.0 | id: "1e2" |
The defensive habit that prevents all of these: quote every string that isn’t obviously a word, especially anything resembling a number, date, or two-letter code. Converting to JSON here is itself a great audit — scan the output for values that changed type unexpectedly.
Indentation rules that trip up hand-written YAML
YAML forbids tabs for indentation — a single tab character fails the parse with a confusingly located error. Sequence items (- item) must align consistently, and a common Kubernetes-manifest bug is a list indented one space differently between siblings, silently creating a different structure rather than an error. When YAML “parses but behaves wrong,” convert it to JSON here: the brackets make the actual structure unambiguous in a way indentation never quite does.
Anchors, aliases, and what conversion does to them
YAML’s &anchor / *alias / <<: merge let one block reuse another — heavily used in CI configs (GitLab CI, docker-compose) to avoid repetition. JSON has no equivalent, so conversion expands every alias into a full copy. That’s correct and lossless for the data, but be aware the round trip won’t restore the anchors: a 40-line YAML with shared defaults can become a 200-line JSON, and converting back yields the expanded form. Treat anchored YAML as source code and its JSON form as compiled output.
Comments don’t survive — plan accordingly
JSON has no comment syntax, so every # explanation in your YAML is dropped on conversion, and there is nothing to restore on the way back. When migrating commented configuration permanently to JSON, move essential comments into the data itself (a "_comment" key or proper documentation). For one-way inspection — converting YAML to JSON just to query it with jq or validate structure — the loss is irrelevant.