Why you need to convert between them
YAML is config-file format — it's designed to be hand-edited by humans and allows comments, multi-line strings, and anchors for reuse. JSON is a wire format — it's designed for machine-to-machine communication and is parsed by every language natively. The most common conversion scenario: you have a YAML config (Kubernetes manifest, GitHub Actions workflow, Docker Compose file) and need to pass part of it to an API that expects JSON, or you get a JSON response from an API and want to edit it as YAML before storing it in a config file.
Three YAML features that don't survive JSON conversion
- CommentsYAML allows
# commentsanywhere. JSON has no comment syntax. When you convert YAML to JSON, all comments are silently dropped — they cannot be round-tripped. If your YAML comments document why a value is set a certain way, keep the YAML source as the canonical file and treat JSON as a derived output. - Anchors and aliasesYAML anchors ("&anchor" and "*alias") let you reuse a value in multiple places. The converter dereferences them — each alias becomes a full copy of the anchored value in the output JSON. This is correct behavior but can produce much larger JSON than the source YAML if anchors were used for DRY config blocks.
- Multi-document streamsA single YAML file can contain multiple documents separated by
---. JSON has no equivalent — one file, one object. Paste one document at a time when converting multi-document YAML.
When JSON is the strictly better choice
For API payloads and data interchange: always JSON. YAML's indentation sensitivity makes it error-prone when generated programmatically — one off-by-two-spaces and the structure silently changes meaning. JSON's explicit braces and brackets are unambiguous in code generation.
For configuration files that humans edit: usually YAML, but only if your toolchain supports it natively. If you find yourself running a converter as part of your deploy pipeline every time someone edits the config, consider switching the canonical format to JSON — the tooling cost isn't worth the indentation convenience.