JSON-YAML Converter Online Gids: Syntax, Tools en Best Practices

Try our free JSON to YAML / YAML to JSON converter →

JSON vs YAML: Syntax Comparison

JSON (JavaScript Object Notation) and YAML (YAML Ain't Markup Language) represent the same data structures but with very different syntax philosophies. JSON prioritizes machine parsing with strict, unambiguous syntax. YAML prioritizes human readability with indentation-based nesting and minimal punctuation.

Here is the same configuration data expressed in both formats side by side:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "ssl": true
  },
  "database": {
    "name": "myapp",
    "replicas": [
      "db1.example.com",
      "db2.example.com"
    ]
  },
  "features": [
    "authentication",
    "logging",
    "rate-limiting"
  ]
}

# Server configuration
server:
  host: localhost
  port: 8080
  ssl: true

# Database settings
database:
  name: myapp
  replicas:
    - db1.example.com
    - db2.example.com

features:
  - authentication
  - logging
  - rate-limiting

The differences are immediately visible: YAML eliminates braces, brackets, and most quotation marks. It uses indentation (2 spaces by convention) to express nesting, dashes for array items, and colons for key-value pairs. Comments are supported with #. JSON requires every string to be double-quoted, every object wrapped in {}, and every array in [].

When to Use JSON vs YAML

The choice between JSON and YAML depends on who or what will read and write the file:

YAML Anchors, Aliases, and Multi-line Strings

YAML provides several powerful features that have no JSON equivalent. These features are why many configuration-heavy ecosystems chose YAML as their format.

Anchors and Aliases

YAML anchors (&) define a reusable block of data, and aliases (*) reference it. This eliminates duplication in configuration files. The merge key (<<) lets you inherit and override mapping values:

# Define reusable defaults with an anchor
defaults: &default_db
  adapter: postgres
  host: localhost
  port: 5432
  pool_size: 10

# Reference with alias and override specific fields
development:
  database:
    <<: *default_db          # Merge all defaults
    database: myapp_dev
    pool_size: 5             # Override pool_size

staging:
  database:
    <<: *default_db
    database: myapp_staging
    host: staging-db.internal

production:
  database:
    <<: *default_db
    database: myapp_prod
    host: prod-db.internal
    pool_size: 25

# After JSON conversion (anchors fully expanded):
# {
#   "defaults": { "adapter": "postgres", "host": "localhost", "port": 5432, "pool_size": 10 },
#   "development": {
#     "database": { "adapter": "postgres", "host": "localhost", "port": 5432, "pool_size": 5, "database": "myapp_dev" }
#   },
#   ...
# }

Multi-line Strings

YAML offers two block scalar styles for multi-line text that are far more readable than JSON's <code>\n</code> escape sequences:

Literal block (|): preserves newlines exactly as written. Use for scripts, SQL, or any text where line breaks matter.

Folded block (>): joins lines with spaces (like HTML). Use for long descriptions or paragraphs.

# Literal block (|) - preserves newlines exactly
script: |
  #!/bin/bash
  echo "Starting deployment..."
  docker compose pull
  docker compose up -d
  echo "Done!"

# Folded block (>) - joins lines with spaces
description: >
  This is a long description
  that spans multiple lines.
  Each newline becomes a space
  in the resulting string.

# Strip trailing newline with |-
sql_query: |-
  SELECT users.name, orders.total
  FROM users
  JOIN orders ON users.id = orders.user_id
  WHERE orders.created_at > '2024-01-01'

# Keep all trailing newlines with |+
message: |+
  Line 1
  Line 2

  (trailing newlines preserved)


# JSON equivalents:
# "script": "#!/bin/bash\necho \"Starting...\n..."
# "description": "This is a long description that spans..."
# "sql_query": "SELECT users.name..."  (no trailing \n)

Chomping indicators control trailing newlines: |+ keeps all trailing newlines, |- strips all trailing newlines, | (default) keeps exactly one.

Converting JSON to YAML in JavaScript (js-yaml)

The js-yaml library is the most widely used YAML parser for JavaScript and Node.js. It provides yaml.load() to parse YAML into JavaScript objects and yaml.dump() to serialize objects back to YAML:

// npm install js-yaml
const yaml = require('js-yaml');
const fs = require('fs');

// ===== JSON to YAML =====
const jsonData = {
  apiVersion: 'apps/v1',
  kind: 'Deployment',
  metadata: { name: 'web-app', labels: { app: 'web' } },
  spec: {
    replicas: 3,
    selector: { matchLabels: { app: 'web' } },
    template: {
      spec: {
        containers: [{
          name: 'app',
          image: 'nginx:1.25',
          ports: [{ containerPort: 80 }]
        }]
      }
    }
  }
};

const yamlOutput = yaml.dump(jsonData, {
  indent: 2,
  lineWidth: 120,
  noRefs: true,       // Don't use YAML anchors
  sortKeys: false,     // Preserve key order
  quotingType: '"',    // Use double quotes
});
console.log(yamlOutput);

// ===== YAML to JSON =====
const yamlString = fs.readFileSync('config.yaml', 'utf8');
const parsed = yaml.load(yamlString);
const jsonString = JSON.stringify(parsed, null, 2);
fs.writeFileSync('config.json', jsonString);

// ===== Handle multi-document YAML =====
const multiDoc = `
---
name: service-a
port: 3000
---
name: service-b
port: 3001
`;
const docs = [];
yaml.loadAll(multiDoc, (doc) => docs.push(doc));
console.log(JSON.stringify(docs, null, 2));
// [{ "name": "service-a", "port": 3000 }, { "name": "service-b", "port": 3001 }]

For TypeScript projects, js-yaml ships with built-in type definitions. You can also use the newer yaml package (npm: yaml) which provides a modern API with document preservation and CST support for round-trip editing that preserves comments.

Try our free JSON to YAML / YAML to JSON converter →

Converting JSON to YAML in Python (PyYAML, ruamel.yaml)

Python has two major YAML libraries. PyYAML is the established standard, while ruamel.yaml is the modern alternative that preserves comments during round-trip conversion:

PyYAML (Standard Library Alternative)

# pip install pyyaml
import yaml
import json

# ===== YAML to JSON =====
yaml_text = """
server:
  host: localhost
  port: 8080
  features:
    - auth
    - logging
  database:
    name: myapp
    ssl: true
"""

# ALWAYS use safe_load (never yaml.load with untrusted input)
data = yaml.safe_load(yaml_text)
json_output = json.dumps(data, indent=2, ensure_ascii=False)
print(json_output)

# ===== JSON to YAML =====
json_text = '{"name": "app", "version": "2.0", "debug": false}'
data = json.loads(json_text)
yaml_output = yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False)
print(yaml_output)

# ===== File conversion =====
with open('config.yaml', 'r') as yf:
    config = yaml.safe_load(yf)

with open('config.json', 'w') as jf:
    json.dump(config, jf, indent=2, ensure_ascii=False)

# ===== Multi-document YAML =====
multi_yaml = """
---
name: doc1
value: 100
---
name: doc2
value: 200
"""
docs = list(yaml.safe_load_all(multi_yaml))
print(json.dumps(docs, indent=2))

ruamel.yaml (Comment-Preserving)

Unlike PyYAML, ruamel.yaml can load a YAML file with comments, modify values, and write it back with comments intact. This makes it ideal for tools that programmatically update configuration files:

# pip install ruamel.yaml
from ruamel.yaml import YAML
from io import StringIO
import json

yaml_handler = YAML()
yaml_handler.preserve_quotes = True

# Load YAML with comments preserved
yaml_text = """
# Application configuration
app:
  name: my-service    # Service name
  port: 3000          # Listen port
  debug: false
"""

data = yaml_handler.load(yaml_text)

# Modify a value
data['app']['port'] = 8080

# Write back - comments are preserved!
output = StringIO()
yaml_handler.dump(data, output)
print(output.getvalue())
# Output still has "# Application configuration" and inline comments

# Convert to JSON (comments lost in JSON, but preserved in YAML round-trip)
json_output = json.dumps(dict(data), indent=2, default=str)
print(json_output)

Converting via Command Line (yq, jq)

Command-line tools are ideal for quick conversions, shell scripts, and CI/CD pipelines. The two most important tools are yq (a YAML processor) and jq (a JSON processor):

yq: The YAML Swiss Army Knife

yq (by Mike Farah) is a lightweight, portable command-line YAML processor that can read, filter, update, and convert YAML files. It uses jq-like syntax:

# Install yq (Mike Farah version)
# macOS: brew install yq
# Linux: snap install yq  OR  wget from GitHub releases
# Windows: choco install yq

# ===== YAML to JSON =====
yq -o=json config.yaml
yq -o=json '.' config.yaml > config.json

# ===== JSON to YAML =====
yq -o=yaml config.json
yq -o=yaml -P '.' config.json > config.yaml  # -P for pretty print

# ===== Query and filter =====
yq '.server.port' config.yaml              # Extract a value
yq '.spec.containers[0].image' deploy.yaml # Array access
yq '.metadata.labels' deploy.yaml          # Get nested object

# ===== Modify in-place =====
yq -i '.server.port = 9090' config.yaml
yq -i '.spec.replicas = 5' deploy.yaml

# ===== Merge multiple files =====
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml override.yaml

# ===== Convert multi-document YAML to JSON array =====
yq -o=json -s '.' multi-doc.yaml

jq for JSON Processing

While jq does not handle YAML natively, you can combine it with yq or Python one-liners for powerful JSON-YAML workflows:

# Pipe yq output through jq for advanced JSON processing
yq -o=json config.yaml | jq '.server'
yq -o=json deploy.yaml | jq '.spec.template.spec.containers[] | .name'

# Use jq to transform JSON, then convert to YAML
cat data.json | jq '{filtered: .items | map(select(.active))}' | yq -o=yaml -P

Quick One-liners

# Python one-liner: YAML to JSON
python3 -c 'import sys,yaml,json; json.dump(yaml.safe_load(sys.stdin),sys.stdout,indent=2)' < config.yaml

# Python one-liner: JSON to YAML
python3 -c 'import sys,yaml,json; print(yaml.dump(json.load(sys.stdin),default_flow_style=False))' < config.json

# Ruby one-liner: YAML to JSON
ruby -ryaml -rjson -e 'puts JSON.pretty_generate(YAML.safe_load(STDIN.read))' < config.yaml

Kubernetes Manifests: A YAML-Heavy Ecosystem

Kubernetes has made YAML the lingua franca of cloud-native infrastructure. Every Kubernetes resource (Pods, Deployments, Services, ConfigMaps, Secrets, Ingresses) is defined in YAML. Understanding YAML is essential for any Kubernetes engineer.

Here is a typical Kubernetes Deployment manifest showcasing common YAML patterns:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-application
  namespace: production
  labels:
    app: web
    version: "2.0"         # Quoted to prevent float interpretation
    environment: production
  annotations:
    description: >-        # Folded block, strip trailing newline
      Production web application deployment
      with auto-scaling and health checks
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: myregistry/web-app:2.0.1
          ports:
            - containerPort: 8080
              protocol: TCP
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: db-credentials
                  key: url
            - name: LOG_LEVEL
              value: "info"        # Quoted to ensure string
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 10
---
# Multiple resources in one file
apiVersion: v1
kind: Service
metadata:
  name: web-service
spec:
  selector:
    app: web
  ports:
    - port: 80
      targetPort: 8080
  type: ClusterIP

Key YAML patterns used in Kubernetes: nested mappings for spec definitions, dash-prefixed sequences for containers and ports, multi-line strings for embedded configs, and labels/annotations for metadata. The <code>---</code> separator allows multiple resources in a single file.

Docker Compose and CI/CD Configuration

Docker Compose and CI/CD platforms like GitHub Actions are another major YAML ecosystem. These files demonstrate YAML's strength for defining complex workflows and service architectures:

Docker Compose (docker-compose.yml)

# docker-compose.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    volumes:
      - ./uploads:/app/uploads
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
      interval: 10s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    command: redis-server --maxmemory 256mb --maxmemory-policy allkeys-lru

volumes:
  postgres_data:

GitHub Actions Workflow

GitHub Actions workflows use YAML with specific patterns like on: triggers, matrix strategies, and step definitions:

# .github/workflows/ci.yml
name: CI Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test
      - run: npm run build

  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to production
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
        run: |
          echo "Deploying to production..."
          ./scripts/deploy.sh

Try our free JSON to YAML / YAML to JSON converter →

YAML Gotchas: Common Pitfalls to Avoid

YAML's flexibility comes with several notorious pitfalls that have bitten developers for decades. Understanding these gotchas will save you hours of debugging.

The Norway Problem (Boolean Coercion)

This is YAML's most infamous gotcha. In YAML 1.1 (used by PyYAML and many other parsers), a surprisingly large set of unquoted values are interpreted as booleans:

# YAML 1.1 boolean coercion (PyYAML, many other parsers)
# These ALL become booleans when unquoted:

countries:
  - US       # String "US" (ok)
  - GB       # String "GB" (ok)
  - NO       # BECOMES: false  (Norway disappears!)
  - FR       # String "FR" (ok)

settings:
  verbose: yes    # BECOMES: true  (not the string "yes")
  debug: no       # BECOMES: false
  feature: on     # BECOMES: true
  legacy: off     # BECOMES: false
  confirm: y      # BECOMES: true
  cancel: n       # BECOMES: false

# FIX: Always quote ambiguous values
countries:
  - "US"
  - "GB"
  - "NO"     # Now correctly a string
  - "FR"

settings:
  verbose: "yes"  # String "yes"
  debug: "no"     # String "no"

The country code NO (Norway) becomes false. Toggle values like on/off become true/false. Even y and n are affected. YAML 1.2 restricts booleans to only true/false, but most parsers still default to 1.1 behavior. The fix: always quote strings that could be misinterpreted.

Indentation Errors

YAML uses spaces only (never tabs) for indentation. A single tab character causes a parse error. Mixed indentation levels within a file create subtle bugs. Always configure your editor to use 2 spaces for YAML files and enable visible whitespace. Add a .editorconfig rule:

# .editorconfig - enforce consistent YAML formatting
[*.{yml,yaml}]
indent_style = space
indent_size = 2
tab_width = 2
insert_final_newline = true
trim_trailing_whitespace = true

# .yamllint.yml - lint configuration
---
extends: default
rules:
  indentation:
    spaces: 2
    indent-sequences: true
  truthy:
    check-keys: true
    allowed-values: ["true", "false"]
  line-length:
    max: 120

Unexpected Boolean Values

Beyond the Norway problem, YAML 1.1 treats these as booleans: TRUE, True, true, YES, Yes, yes, ON, On, on, Y, y (all become true), and their false counterparts. Version numbers like 1.0 become floats, and dates like 2024-01-15 may become date objects. Quote everything that is not obviously a string:

# More unexpected type coercions in YAML:

version: 1.0        # BECOMES: float 1.0 (not string "1.0")
version: "1.0"      # String "1.0" (correct)

octal: 0o17         # BECOMES: integer 15
hex: 0xFF           # BECOMES: integer 255

date: 2024-01-15    # BECOMES: date object (in some parsers)
date: "2024-01-15"  # String "2024-01-15" (correct)

null_trap: null      # BECOMES: null (not string "null")
null_trap: ~         # ALSO BECOMES: null
null_trap: ""        # Empty string (if you want empty, not null)

# Special float values
infinity: .inf       # BECOMES: Infinity
not_a_number: .nan   # BECOMES: NaN

# Rule of thumb: if it's not obviously a string, quote it

YAML Security: Avoiding Code Execution

YAML parsers can be dangerously powerful. The YAML specification includes tags that allow parsers to instantiate arbitrary objects, which can lead to remote code execution (RCE) vulnerabilities.

The dangerous pattern (Python): yaml.load(data, Loader=yaml.FullLoader) or the older yaml.load(data) allows constructing arbitrary Python objects from YAML tags like !!python/object/apply:os.system.

# DANGEROUS - Never do this with untrusted YAML input!
import yaml

# This YAML payload can execute arbitrary commands:
malicious_yaml = """
!!python/object/apply:os.system
  args: ['echo HACKED > /tmp/pwned']
"""

# BAD: yaml.load() with FullLoader allows object construction
# data = yaml.load(malicious_yaml, Loader=yaml.FullLoader)  # DANGER!

# GOOD: safe_load() only allows basic types
data = yaml.safe_load(malicious_yaml)  # Raises ConstructorError

# ALSO GOOD: ruamel.yaml with safe type
from ruamel.yaml import YAML
safe_yaml = YAML(typ='safe')
data = safe_yaml.load(malicious_yaml)  # Raises error

The safe pattern: Always use yaml.safe_load() (PyYAML) or YAML(typ="safe") (ruamel.yaml). These restrict parsing to basic data types (strings, numbers, lists, dicts) and reject any object construction tags.

In JavaScript, js-yaml defaults to safe loading since v4. In older versions, avoid yaml.load() with FULL_SCHEMA. In Go, the standard gopkg.in/yaml.v3 is safe by default.

Additional security considerations: limit input size to prevent denial-of-service via deeply nested structures or anchor bombs (billion laughs attack). Validate YAML against a schema after parsing to catch unexpected fields. Never deserialize YAML from untrusted sources without safe loading.

Feature Comparison Table

Here is a comprehensive comparison of JSON and YAML features to help you choose the right format:

Frequently Asked Questions

What is the difference between JSON and YAML?

JSON uses braces, brackets, and double-quoted strings with strict syntax. YAML uses indentation-based nesting with minimal punctuation. YAML supports comments (#), multi-line strings (| and >), and anchors/aliases for data reuse. JSON is universally supported in programming languages and faster to parse. YAML is more human-readable and preferred for configuration files. Technically, YAML is a superset of JSON, meaning every valid JSON document is also valid YAML.

How do I convert JSON to YAML online?

Paste your JSON into an online JSON to YAML converter tool. The tool parses the JSON, converts the data structures, and outputs YAML with proper indentation. Our free DevToolBox converter handles nested objects, arrays, special characters, and large files. You can also convert YAML back to JSON with a single click.

Is YAML better than JSON for configuration files?

Yes, YAML is generally better for configuration files that humans edit frequently. It supports comments for documentation, multi-line strings for readability, and cleaner syntax without braces and quotes. However, JSON is better for machine-generated configs or when you need strict, unambiguous parsing. Kubernetes, Docker Compose, and CI/CD platforms chose YAML specifically for its human-friendliness.

What is the Norway problem in YAML?

The Norway problem refers to YAML 1.1 interpreting the country code NO (for Norway) as the boolean value false. This happens because YAML 1.1 treats yes, no, on, off, y, and n (case-insensitive) as boolean values. The fix is to quote strings that could be misinterpreted: use "NO" instead of NO. YAML 1.2 restricts booleans to only true and false, but many parsers (including PyYAML) still default to 1.1 behavior.

Why should I use yaml.safe_load() instead of yaml.load() in Python?

yaml.load() with FullLoader or the older default Loader can instantiate arbitrary Python objects from YAML tags like !!python/object/apply:os.system, enabling remote code execution. yaml.safe_load() restricts parsing to basic data types (strings, numbers, lists, dicts) and rejects dangerous tags. Always use safe_load() when parsing YAML from any untrusted or external source.

Can I preserve YAML comments when converting to JSON and back?

No, standard conversion loses all YAML comments because JSON has no comment syntax. If you convert YAML to JSON and back to YAML, comments are permanently lost. To preserve comments during programmatic YAML editing, use ruamel.yaml in Python or the yaml CST parser in JavaScript. These libraries maintain the original document structure including comments during round-trip operations.

How do I convert YAML to JSON from the command line?

The easiest method is using yq: run "yq -o=json file.yaml" to convert YAML to JSON. For JSON to YAML: "yq -o=yaml file.json". You can also use Python one-liners: "python3 -c 'import sys,yaml,json; json.dump(yaml.safe_load(sys.stdin),sys.stdout,indent=2)' < file.yaml". Install yq via brew install yq (macOS), snap install yq (Linux), or download from GitHub.

What YAML features are lost when converting to JSON?

Several YAML features have no JSON equivalent and are lost or transformed during conversion: comments (# ...) are discarded, anchors and aliases are fully expanded (dereferenced), multi-line block scalars (| and >) become single strings with \n, multiple documents (--- separator) must become a JSON array, and YAML-specific types like dates and binary data are converted to strings or numbers.

Understanding the relationship between JSON and YAML is essential for modern software development. JSON dominates API communication and data exchange, while YAML rules the configuration world across Kubernetes, Docker, CI/CD, and infrastructure-as-code. By mastering the conversion between these formats, avoiding common pitfalls like the Norway problem, and following security best practices with safe loading, you can work confidently in both ecosystems.

Convert between JSON and YAML instantly with our free online tool. →