Common JSON to YAML Conversion Errors and How to Fix Them

Indentation errors

YAML structure is defined by spaces, not braces. JSON tells you exactly where an object ends with }; YAML expects every nested key to be indented one consistent step (almost always two spaces in tooling ecosystems) under its parent. When you convert JSON to YAML, a sloppy formatter—or manual edits—can shift a child left by one column so it becomes a sibling of what you meant as its parent.

Picture turning this JSON into YAML:

If port aligns with server instead of nesting under it, parsers treat port as a top-level key, not server.port. Some loaders then merge unexpectedly or fail with “mapping values are not allowed here.” The json to yaml errors category that wastes the most engineering time is exactly this: valid-looking text that parses into the wrong tree.

Fix: pick one indent width (2 spaces), forbid tabs in committed YAML, and diff converter output against a known-good emitter (yq, your IDE, or YAML Validator). If you need a repeatable workflow from scratch, see how to convert JSON to YAML before you automate pipelines.

Editor features make this worse: “snippets” that insert tabs, pretty-printers that reflow only half the file, or paste buffers that normalize CRLF while shifting spaces. When debugging json to yaml errors, collapse whitespace visibly (cat -A or IDE “render whitespace”) before blaming the converter.

Data type issues

JSON literals are explicit: true, false, null, numbers, strings. YAML 1.1 (still common in the wild) treats yes / no / on / off as booleans when unquoted. JSON never emits those tokens—but humans editing YAML after conversion sometimes introduce them, or a round-trip through another tool swaps quoting.

Worse: unquoted null in YAML is fine, but a stray Null or NULL can behave differently depending on the parser mode. Same for timestamps: a string like 2024-01-15 may become a date type if the loader is permissive.

Depending on the parser, yes becomes boolean true, null stays null, and cutoff may become a parsed date, not a six-character string—breaking APIs that expect "2024-01-15" verbatim.

Fix: quote anything that must stay a string: enabled: "yes" when the contract wants the word “yes”, cutoff: "2024-01-15" when consumers compare strings. After conversion, assert types in tests or schema validation (JSON Schema, OpenAPI, or strict YAML loaders in CI).

Numeric surprises matter too: JSON 001 is invalid; YAML might happily parse leading-zero-looking tokens differently depending on version. Stick to JSON-normal forms before conversion, then quote identifiers that must preserve leading zeros (ZIP codes, version segments treated as strings).

Array formatting problems

JSON arrays are bounded by [ … ]; sequence items cannot “drift.” YAML lists use - markers whose indentation level decides which object owns the items. A classic failure after json to yaml automation is a single-element array that becomes an inline scalar, or list items that glue to the wrong parent key.

JSON like {"items": [{"id": 1}, {"id": 2}]} must become a - list indented under items:. If one - is dedented, you suddenly have multiple documents or a parse error. Multi-line strings and nested lists amplify the problem—Kubernetes manifests and CI configs are full of both.

Empty arrays matter: [] in JSON should become explicit YAML list syntax (items: [] or items:\n [] patterns depending on style)—avoid ambiguous scalars like items: with nothing following unless your linter forbids it. Mixed arrays (objects and strings in one list) are valid JSON but easy to mis-indent once flattened.

Fix: never hand-merge list markers after conversion; regenerate from JSON when lists look suspicious. Visually verify that every - shares the same column as its siblings and sits deeper than the key it belongs to.

Example: lists that survived conversion intact

From JSON {"routes": [{"path": "/api", "upstream": "svc"}, {"path": "/health", "upstream": "direct"}]}, stable YAML keeps sibling - blocks aligned:

If upstream: direct aligns under routes: instead of under the second - path, you just invented a different routing table—a subtle class of json to yaml errors that passes lint yet breaks routing.

Special characters

Strings containing :, #, {, }, [, ], or leading - need quoting in YAML or the scanner attaches meaning to punctuation (# starts a comment; : starts a mapping value). URLs and connection_string values are frequent victims.

Everything after # can be treated as a comment unless you quote:

`yaml
message: "Error: disk full (see log #42)"
`

Fix: adopt a simple rule: if the value looks like code, a URL, or contains # or : , wrap it in double quotes and escape internal " as \" when needed.

Multi-line strings from JSON (\\n) sometimes explode into YAML literal (|) or folded (>) blocks during tooling hops—fine if every downstream loader agrees. If not, keep quoted single-line escapes until you standardize.

How to avoid errors

Treat JSON → YAML as a compile step, not a one-off paste:

When errors still slip through, JSON Validator on the source JSON eliminates half the “garbage in” cases before they become confusing YAML trees.

If you are shipping configs to Kubernetes after conversion, combine this checklist with the worked manifest walkthrough in Convert JSON to YAML for Kubernetes (With Examples).

Most json to yaml errors are not mysterious—they are indentation, implicit typing, list ownership, or quoting. Make those four dimensions boringly explicit and your configs stop failing at 11 p.m. on deploy night.