Developer tools · Syntax converters
How JSON to YAML conversion works: quoting, indentation and flow style
· How it works
json yaml developer-workflow
JSON to YAML looks like a matter of deleting braces, but a converter makes real decisions about which strings need quotes and when to use block versus flow style. This post walks through those decisions.
The braces disappear, but where do the quotes go? — a JSON payload converted to YAML and the mixture of quoted and bare strings in the result
Removing braces and quotation marks does not make a JSON object into a trustworthy YAML file. The converter must decide how a nested mapping, array, string and newline are represented and whether a value that looks like a number or Boolean stays text. A DevOps engineer moving an API service definition to Compose needs those decisions to be predictable before copying the result into a deployment directory. Conversion changes syntax, not the service’s actual configuration.
JSON is (almost) already YAML — why the input is valid YAML 1.2 flow style before conversion even starts
YAML 1.2 treats JSON syntax as an allowed flow-style subset for ordinary JSON-shaped data, which explains why a JSON object is already close to YAML. But a useful conversion typically switches to human-readable block-style indentation. The input is parsed as JSON first; arbitrary shell commands are never executed. ToolAcre loads YAML through a restricted schema on the reverse path, rejects unsafe tags and bounds alias expansion, so a converter cannot be used to instantiate arbitrary objects from an untrusted !!js/function tag.
Block style versus flow style — how a converter chooses indentation-based mappings and sequences over braces and brackets, and what the indent depth means
Block style uses indented key/value pairs and lines beginning with a dash for array items: an image string under services.web is indented beneath web, while ports becomes a sequence. Flow style keeps JSON-like braces and brackets. ToolAcre uses js-yaml dump with two-space indentation by default, no references and an unlimited line width setting, rather than merely replacing punctuation with a regular expression. Changing the indent width affects readability, not the actual keys or array order.
Which strings must stay quoted — values that would otherwise become booleans, numbers, nulls or dates, and strings with colons, hashes or leading spaces
Some strings must be quoted to survive another parser: "false" should remain text rather than Boolean false, "2026-09-28" should not silently become a date in a YAML 1.1 consumer, and a colon followed by space can be mistaken for mapping syntax. ToolAcre’s dumper chooses protective quotes, including compatibility choices for older YAML readers. Quoting an ordinary image reference with a colon is not always required, and gratuitously removing the quotes that are present can break a round trip. Verify types as well as visual appearance.
Multi-line strings — how a newline inside a JSON string can become a literal (|) or folded (>) block scalar
A JSON string containing an actual newline may be rendered as a YAML block scalar with |. The |- form strips the final newline, whereas | preserves it; > would fold some line breaks into spaces. Those indicators describe data, not formatting garnish. ToolAcre’s dumper chooses a representation that can read back to the original string rather than always forcing one style. After conversion, inspect a multi-line environment value or certificate carefully: indentation errors here can change what the application receives.
Worked example: converting a service definition — a nested JSON object to YAML, with each quoting and style decision annotated
For a concrete JSON object, use services.web with image "example/web:1", ports ["8080:80"], and environment keys DEBUG="false", RELEASE="2026-09-28" and MESSAGE="line one\nline two". ToolAcre emits image: example/web:1 and a ports list; DEBUG becomes quoted 'false', RELEASE quoted '2026-09-28', and MESSAGE uses a |- block with two indented lines. Each choice protects the original types. Run the panel’s round-trip check before saving as compose.yaml; the converter cannot tell whether the image exists or the service will start.
What this does not cover — adding comments, anchors or a custom key order, none of which exist in the JSON source to be carried over
JSON has no comments, anchors or aliases to preserve: a converter cannot recover them from input that never contained them. It also cannot infer Compose-specific secrets management, a custom key order or Kubernetes API-version validity. Two YAML files can serialize the same data yet use different whitespace and quote styles. Review the result in the target program and avoid pasting real API tokens into external conversion services.
Takeaway: conversion is a re-serialisation with rules — and how the Syntax converters panel produces the YAML in your browser
Conversion is parse and re-serialize under a set of rules, not a deletion of punctuation. Syntax converters performs those operations in your browser; inspect a sensitive configuration locally and run a round trip on a small test object before applying the method to a larger file. If a quoted value changes type on the way back, the formatting is not merely cosmetic and needs investigation.