YAML to JSON Conversion Pitfalls

A Compose file looks fine in the editor. You convert it to JSON for a Node script, and the parser explodes - or worse, it succeeds with "on" as a boolean and a replica count that became the string "3". YAML and JSON overlap, but they are not the same language. Treating conversion as a lossless round-trip is the usual source of the bug.

This guide walks through the failures that show up in Kubernetes, Docker Compose, Helm, and CI configs, and how to check them with Utilitoo's browser converters before the payload hits a cluster or an API.

What actually maps

For everyday config, the mapping is straightforward:

That table is enough until it is not. YAML is designed for humans: optional quotes, significant whitespace, multiple ways to write the same value. JSON is designed for machines: quotes required, commas forbidden at the end of lists, one document per parse in most APIs.

If the destination is a JavaScript JSON.parse, a strict schema, or an HTTP body, write YAML as if it were already JSON-shaped: mappings, sequences, and scalars only. Save YAML-only features (anchors, tags, multiple documents) for files that will stay YAML.

Pitfall 1: Indentation and tabs

YAML structure is the whitespace. A tab mixed into a spaces-only file, a missing space after a colon, or a list item that does not line up with its siblings will fail the parse before any JSON exists.

Typical scene: A manifest copied from Slack or a wiki. Invisible tabs survived the paste. The error points at a line that "looks" aligned.

What to do: Re-indent in YAML Formatter with spaces, then convert with YAML to JSON. If the formatter already errors, fix that first - conversion cannot invent structure the parser could not read.

Do not "fix" YAML by stuffing it into JSON Validator. Validator errors about unexpected tokens are telling you the paste is still YAML, not that JSON is slightly malformed.

Pitfall 2: Types you did not think you wrote

YAML guesses types. That is convenient in Helm values and a hazard in APIs.

Examples that bite people:

• country: NO can become boolean false in some parsers (Norway's ISO code).
• version: 1.10 may become the number 1.1 in naive parsers, or stay a float you did not want as a string.
• on, off, yes, no are boolean-ish in older YAML 1.1 habits. YAML 1.2 and JSON-oriented loaders are stricter, but you should not assume which library your converter uses.
• A replica count written as replicas: "3" stays a string. Unquoted 3 becomes a number. Kubernetes often accepts both; your TypeScript type will not.

What to do: Quote anything that must remain a string ("NO", "1.10", "on"). After conversion, skim the JSON for booleans and numbers you did not intend. Round-trip with JSON to YAML only after the JSON looks right - converting junk back to YAML just pretty-prints the mistake.

Pitfall 3: Multiline strings

YAML has literal (|) and folded (>) block scalars. JSON has one string type, with \n escapes.

When you convert YAML to JSON:

• A | block usually becomes a single JSON string with embedded newlines.
• A > block may collapse newlines to spaces depending on the chomping indicator and the library.

When you convert JSON to YAML, long strings often come out as quoted single-line values, not as | blocks. That is valid YAML. It is ugly to edit. If humans will maintain the file, rewrite the long strings as block scalars in YAML after the first conversion, then treat YAML as the source of truth.

Typical scene: A GitHub Actions run: script or a Cloud-init user-data blob. After JSON round-trip, the script is one escaped line. CI still runs it; nobody can review it.

Pitfall 4: Anchors, aliases, and multiple documents

YAML anchors (&db) and aliases (*db) DRY up repeated blocks. JSON has no equivalent. A converter that expands aliases will duplicate objects. A converter that rejects them will error. Either way, the JSON is not a 1:1 picture of the YAML source.

--- separators start another YAML document in the same file. Kubernetes kubectl accepts multi-doc YAML. JSON.parse does not accept two objects glued together. Convert one document at a time, or split the file first.

What to do: If you need JSON for a test fixture, expand or flatten the YAML until it is a single mapping or sequence with no aliases. Keep the anchored original in git; generate JSON as a build artifact if you must.

Pitfall 5: Duplicate keys and comments

JSON objects cannot have duplicate keys in any useful sense - the last one wins, or the parser errors. YAML technically allows duplicate keys; many linters forbid them. Comments (#) disappear on conversion. That is correct (JSON has no comments) and easy to forget when the comment was the only note about a dangerous default.

Typical scene: Two env: keys in a Compose service. YAML may keep both or merge badly. JSON keeps one. Production is missing half the variables.

A conversion checklist

1. Decide the source of truth. Humans edit YAML; machines consume JSON - or the reverse. Do not ping-pong both files in git.
2. Format and parse YAML first in YAML Formatter so indentation errors show up before conversion.
3. Convert with YAML to JSON (or JSON to YAML if you started from an API dump).
4. Validate JSON if the next consumer is strict. Trailing commas and smart quotes from docs sites are JSON problems, not YAML problems.
5. Read the types. Scan for unexpected true/false/null and for numbers that should have been versions or IDs.
6. Diff the result against a known-good fixture before you apply it to a cluster.

How the Utilitoo tools fit

• YAML to JSON - parse a config humans edited and emit objects and arrays for scripts, tests, and APIs
• JSON to YAML - turn an API or admin export into indented YAML for Helm, Compose, or review
• YAML Formatter - fix spaces vs tabs and see parse errors before you convert
• JSON Validator - locate trailing commas and smart quotes when JSON is the input, not YAML

Everything runs in the browser. Paste placeholders, not live cluster secrets, and redact screenshots either way.

Common mistakes

Bottom line

YAML-to-JSON bugs are usually type and whitespace bugs, not missing features in the converter. Keep configs JSON-compatible when JSON is the destination, quote strings that look like booleans or versions, and format before you convert.

Utilitoo's YAML to JSON, JSON to YAML, and YAML Formatter are for that check: local, fast, and specific enough that you can see the structure change before CI or kubectl does.