JSON to YAML Converter

When to use YAML instead of JSON

JSON and YAML solve the same problem — structured data serialization — but they optimise for different audiences. JSON is designed to be consumed by machines. YAML is designed to be written and read by humans. That single design decision cascades into almost every difference between them.

Use YAML when humans are the primary editors. Configuration files, CI/CD pipelines, infrastructure-as-code manifests, and deployment definitions are all edited by engineers daily. YAML's removal of braces, quotes, and commas — combined with its support for comments — makes it significantly faster to read and edit at a glance than equivalent JSON.

Use JSON when machines are the primary consumers. REST API payloads, npm package metadata, browser localStorage, and most SDK configurations use JSON because every language has a reliable JSON parser in its standard library and the format is unambiguous by design.

Syntax differences explained

The same configuration in both formats makes the differences concrete:

// JSON
{
  "server": {
    "host": "0.0.0.0",
    "port": 8080,
    "tls": true
  },
  "features": ["json", "yaml", "csv"]
}

# YAML — same data, no braces, no quotes, comments allowed
server:
  host: 0.0.0.0
  port: 8080
  tls: true
features:
  - json
  - yaml
  - csv

YAML uses indentation (typically 2 spaces) to represent nesting instead of braces. Keys and most string values do not need quotes. Lists become sequences with - prefixes instead of square bracket notation. Comments start with # and are ignored by parsers — JSON has no comment syntax at all.

YAML gotchas — the Norway problem and friends

YAML's automatic type inference is its most convenient feature and its most dangerous one. YAML 1.1 (which many parsers still use) interprets several bare values in ways that bite developers:

The Norway problem

# YAML 1.1 — "NO" is a boolean false
country_code: NO  # parsed as false, not the string "NO"

# Fix: quote it
country_code: "NO"

YAML 1.1 treated a long list of values as booleans: y, Y, yes, Yes, YES, n, N, no, No, NO, true, True, TRUE, false, False, FALSE, on, On, ON, off, Off, OFF. YAML 1.2 restricts this to only true and false, but many real-world parsers (including older PyYAML versions) still use 1.1 rules.

Octal number interpretation

# YAML 1.1 — leading zero triggers octal
file_mode: 0755  # parsed as decimal 493, not 755

# Fix: quote or use YAML 1.2 parser
file_mode: "0755"

Multiline strings

# Literal block scalar (|) — preserves newlines
message: |
  Line one.
  Line two.
  Line three.

# Folded block scalar (>) — folds newlines to spaces
description: >
  This long paragraph will be
  folded into a single line by
  the YAML parser.

Multiline strings are one of YAML's clearest wins over JSON. Embedding a multi-paragraph string in JSON requires awkward \n escape sequences. YAML's block scalars make it readable.

YAML in the wild: Kubernetes, GitHub Actions, Docker

YAML is the dominant format for declarative infrastructure. If you work in any of these ecosystems, you write YAML every day:

Kubernetes — every resource definition (Pod, Deployment, Service, ConfigMap) is a YAML manifest applied via kubectl apply -f. Kubernetes uses the Go YAML library which is YAML 1.2, so the Norway problem doesn't bite — but indentation errors certainly do.

GitHub Actions — every workflow file in .github/workflows/ is YAML. The most common error: using on (the workflow trigger key) without quoting — some parsers interpret bare on as a boolean. Use "on": or the alias true.

Docker Compose — docker-compose.yml is YAML. Port mappings (3000:3000) must be quoted to prevent the parser interpreting the colon-separated format as a sexagesimal (base-60) number in older parsers.

Frequently Asked Questions