JSON to YAML that quotes what must be quoted

When leaving it bare would make a reader produce something other than that string — which is a longer list than most people expect. It covers the empty string, anything with leading or trailing spaces, anything starting with an indicator character such as - ? : , [ ] { } # & * ! | > % @ or a quote, anything containing a colon followed by a space or a space followed by #, and anything that resolves to a number, boolean, null, date, infinity or NaN. Everything else can stay plain, which is why 1.2.3 and sh -c come out unquoted here: neither resolves to another type.

Because a YAML 1.1 reader turns bare no into the boolean false, and most language bindings are still 1.1. This is the Norway problem: a list of country codes containing NO loses Norway and gains a false. The same rule catches y, yes, n, on and off, and it applies to keys as much as values. Switch the target to “YAML 1.2 readers only” and the quotes come off, because the 1.2 core schema resolves only true and false.

As a literal block scalar introduced by |, with the text indented underneath instead of escaped into one line. A string ending without a newline gets |-, one ending with a single newline gets plain |, and one ending with several gets |+ — those are the strip, clip and keep chomping indicators, and choosing the wrong one changes the value. A line with trailing whitespace, or a control character anywhere in the string, forces a double-quoted one-liner instead, because a block scalar cannot represent either without ambiguity.

Never a tab — YAML forbids tabs in indentation outright, and no option here will emit one. Two spaces is the convention almost everywhere (Kubernetes, GitHub Actions, docker-compose, Ansible) and is what this page does by default; four is available and equally valid. What actually matters is consistency inside a document, since indentation is the only thing expressing structure.

As {} and [], because block style has no way to spell an empty collection. Those two are the only flow syntax that appears in block mode, and they are worth keeping rather than dropping: a key with nothing after it parses as null, not as an empty map, so omitting the braces would change the value your consumer receives.

Usually, by around a third: a 2.83 MB indented JSON payload of 12,000 records became 1.95 MB of YAML here, 31% smaller. The saving comes from dropping every quote around a key, every comma at the end of a line, and every brace and bracket — block style spends indentation instead of punctuation. Flow style for short lists gives some of that back and buys compactness in the other direction.

Yes, and switching on the leading --- makes it a well-formed document in a stream, which is how multi-resource manifests are written. Keep the target set to YAML 1.1 for those, because Kubernetes parses through Go libraries and GitHub Actions through a 1.1-era reader; the extra quotes around yes, no and 0755 are exactly what keeps a mode or a feature flag from changing type when the file is applied.