JSON to YAML Conversion: A Complete Migration Guide

JSON and YAML represent the same data structures with different syntax. Converting between them is straightforward in most cases, but edge cases around types, multiline strings, and comments require attention. This guide covers the complete mapping between formats.

Syntax Mapping

Objects / Mappings

JSON:

{
  "database": {
    "host": "localhost",
    "port": 5432,
    "name": "myapp"
  }
}

YAML:

database:
  host: localhost
  port: 5432
  name: myapp

Arrays / Sequences

JSON:

{
  "servers": ["web1", "web2", "web3"]
}

YAML:

servers:
  - web1
  - web2
  - web3

Nested Structures

JSON:

{
  "services": [
    {
      "name": "api",
      "ports": [8080, 8443],
      "env": {"NODE_ENV": "production"}
    }
  ]
}

YAML:

services:
  - name: api
    ports:
      - 8080
      - 8443
    env:
      NODE_ENV: production

Convert instantly with our JSON to YAML converter.

Edge Cases to Watch

1. Comments

YAML supports comments; JSON does not. When converting YAML to JSON, all comments are lost:

# This comment will be lost in JSON
database:
  host: localhost  # Also lost

2. Multiline Strings

YAML has powerful multiline syntax that JSON lacks:

description: |
  This is a multi-line
  string that preserves
  line breaks.

In JSON, this becomes:

{
  "description": "This is a multi-line\nstring that preserves\nline breaks.\n"
}

3. Type Ambiguity

YAML auto-detects types, which can cause issues:

version: 1.0    # Float, not string "1.0"
port: 080       # Octal 64, not string "080"
country: NO     # Boolean false, not string "NO"

In JSON, types are explicit:

{
  "version": "1.0",
  "port": "080",
  "country": "NO"
}

When converting JSON to YAML, add quotes around values that could be misinterpreted.

4. Null Values

Both support null, but the syntax differs:

value: null     # Explicit
value: ~        # YAML shorthand
value:          # Empty value = null

{ "value": null }

5. Special Characters in Keys

JSON keys can contain any unicode character. YAML keys with special characters need quoting:

"content-type": "application/json"  # Hyphen needs quotes
simple_key: value                    # Underscore is fine

Command-Line Conversion

Using yq (YAML processor)

# JSON to YAML
yq -P input.json > output.yaml

# YAML to JSON
yq -o=json input.yaml > output.json

Using Python

# JSON to YAML
python3 -c "import json, yaml, sys; print(yaml.dump(json.load(sys.stdin), default_flow_style=False))" < input.json > output.yaml

# YAML to JSON
python3 -c "import json, yaml, sys; print(json.dumps(yaml.safe_load(sys.stdin), indent=2))" < input.yaml > output.json

Using jq + yq together

# Process JSON, output as YAML
cat config.json | jq '.database' | yq -P

When to Use Each Format

Use JSON for: API communication, data storage, machine-generated configs, browser environments.

Use YAML for: Human-edited configs, Docker Compose, Kubernetes, CI/CD pipelines, Ansible.

For a deeper comparison, see our YAML vs JSON article.

FAQ

Is YAML a superset of JSON?

Yes, since YAML 1.2 (2009), every valid JSON document is also valid YAML. A YAML parser can parse JSON directly. However, the reverse is not true — YAML features like comments, anchors, and multiline strings have no JSON equivalent.

Which is faster to parse, JSON or YAML?

JSON is significantly faster to parse in virtually all languages. JSON parsers are simpler because the format has less syntax to handle. For configuration files loaded once at startup, the difference is negligible. For high-throughput data processing, JSON is the clear choice.

Related Resources

• JSON to YAML Converter — Convert between formats instantly
• YAML vs JSON — Detailed format comparison
• YAML Syntax Tutorial — Learn YAML from scratch