SwitchPDF
All articles
Developer August 14, 2026 4 min read

Converting JSON to YAML for Kubernetes and Docker Compose

Your API speaks JSON, your infrastructure speaks YAML. Converting between them has three gotchas worth knowing about.

JSON and YAML describe the same data structures, so conversion is mechanical. Where it goes wrong is the handful of places YAML is more permissive than JSON, and quietly changes meaning.

Why the conversion comes up

  • kubectl get -o json returns JSON; your manifests in git are YAML
  • A vendor documents their config as JSON; your stack is Docker Compose
  • You're moving a GitHub Actions or Ansible file between formats
  • Someone pasted a JSON blob and your linter wants YAML

Gotcha 1: the Norway problem

YAML 1.1 interprets unquoted no, yes, on, off, true and false as booleans. The country code for Norway is NO. So:

country: NO      # this is the boolean false
country: "NO"    # this is the string you meant

Any short string that looks like a boolean needs quoting. Same story for version numbers: version: 1.10 becomes the number 1.1.

Gotcha 2: leading zeros

zip: 07030       # parsed as octal in YAML 1.1
zip: "07030"     # the postcode you meant

Postcodes, phone numbers and account IDs all suffer from this. If it has a leading zero and isn't arithmetic, quote it.

Gotcha 3: indentation is data

JSON's braces make nesting explicit. YAML uses whitespace, so a two-space slip changes which parent a key belongs to — and it often stays valid YAML, just wrong. This is why converting by hand is a bad idea for anything deep.

Converting cleanly

SwitchPDF JSON to YAML converts in both directions in your browser. Nothing is uploaded, which matters because infrastructure config routinely contains internal hostnames, ARNs, bucket names and cluster topology — exactly the material you shouldn't paste into a random web form.

Round-tripping is the fastest sanity check available: convert JSON → YAML → JSON and diff against the original. If anything changed, one of the gotchas above caught you.

When to keep JSON

YAML is friendlier to read and write. JSON is friendlier to machines and has one fewer ambiguity per line. For files a human edits weekly, use YAML. For files a program generates and another program consumes, JSON removes a whole class of parsing surprise.

Bottom line

Quote anything that could be read as a boolean, a number or an octal. Round-trip the result and diff it. Those two habits catch essentially every conversion bug.

Related articles