JSON ⇄ YAML Converter

Why two formats for the same data exist

JSON and YAML describe essentially the same data model — nested mappings, sequences and scalars — but they were designed for opposite readers. JSON was extracted from JavaScript literal syntax and optimised for machines: unambiguous, fast to parse, and wide open to exploit in the days when eval() was the parser. YAML was designed for humans writing configuration by hand: indentation instead of braces, comments, and far fewer quote characters.

The practical consequence is a clean split that most teams converge on:

• APIs and data at rest → JSON. It is faster to parse, has a formal specification (RFC 8259), and every language has a mature implementation.
• Configuration humans edit → YAML. Kubernetes manifests, Docker Compose, GitHub Actions, Ansible, and OpenAPI specs all default to YAML because people write them by hand and need comments.

A side-by-side comparison

// JSON — explicit, verbose, no comments
{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "web"
  },
  "spec": {
    "replicas": 3,
    "containers": [
      { "name": "nginx", "image": "nginx:1.27" }
    ]
  }
}

# YAML — indentation-based, comments allowed, quotes rarely needed
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  containers:
    - name: nginx
      image: nginx:1.27
      # bump to 1.28 after the CVE patch lands

What does not survive the round trip

YAML is a strict superset of JSON in expressiveness, but a superset in one direction only. Converting JSON → YAML is always lossless. Converting YAML → JSON can lose information, and you should know where before you rely on it:

Comments

They are dropped. There is nowhere to put them in JSON. If you round-trip a heavily-commented YAML file through JSON, your documentation disappears.

Anchors, aliases and merge keys

YAML supports &anchor, *alias and the << merge key for reuse. JSON has no equivalent, so parsers expand them — you get the resolved data, but you lose the structure that made the file maintainable.

Multi-document files

A single YAML file can contain several documents separated by ---. JSON has no such concept. Most converters (including this one) process the first document or flatten them; check the result if your input has separators.

Tags and custom types

!!str, !!binary, !CustomTag and similar have no JSON representation. This converter keeps to the common structural subset — mappings, sequences and scalars — which covers the overwhelming majority of real configuration files.

Implicit typing surprises

This is the one that bites people. In YAML, version: 1.10 is a number and serialises as 1.1, while version: "1.10" is a string. Country code no: false parses as a boolean in YAML 1.1. If a value's type matters, quote it explicitly rather than trusting inference:

version: "1.10"     # string — survives round trip
country: "no"       # string, not boolean false
port: "8080"        # string if your consumer expects a string

The Norway problem, and other real-world footguns

YAML 1.1 treats y, yes, no, on, off and ~ as booleans and nulls. A config file listing two-letter country codes breaks the moment it contains no: Norway, because no becomes false. YAML 1.2 largely fixed this, but parsers vary — Docker Compose and several Python libraries still exhibit 1.1 behaviour. Quote anything that could be misread.

Choosing a format for a new project

Ask one question: will a human type this by hand? If yes, choose YAML — the comment support and reduced punctuation are worth the parsing quirks. If the file is generated, consumed by machines, or transmitted over a network, choose JSON — the specification is tighter, the parsers are faster, and you will never debug an indentation error at 2 a.m.

Frequently asked questions