Data & Format

Free JSON to YAML Converter Online

Convert JSON to YAML or YAML to JSON. Bidirectional, with syntax validation.

What is YAML?

YAML (YAML Ain't Markup Language — a recursive acronym) is a human-readable data serialization language designed to be easy to write and understand. It was created in 2001 as a simpler alternative to XML and has become the dominant format for configuration files across the software industry. Docker Compose, Kubernetes, GitHub Actions, Ansible, Helm charts, and most CI/CD platforms all use YAML as their primary configuration language.

Unlike JSON, which uses curly braces and square brackets to denote structure, YAML expresses hierarchy through indentation. A child key is simply indented two spaces further than its parent. This approach eliminates most of the punctuation noise in JSON, making YAML documents far easier to scan and edit by hand.

YAML 1.2 is formally a superset of JSON — every valid JSON document can be parsed by a YAML 1.2 parser without modification. This makes YAML an excellent migration path: you can start with valid JSON and gradually adopt YAML conventions like comments and block scalars.

JSON vs YAML — detailed comparison

Understanding the specific differences between the two formats helps you choose the right tool and avoid common conversion pitfalls.

FeatureJSONYAML
CommentsNot supported# lines are comments
StringsAlways double-quotedUnquoted, single, or double quoted
Booleanstrue / false onlytrue, false, yes, no, on, off
Nullnull onlynull or ~
MultilineEscape \n in strings| (literal) or > (folded) blocks
AnchorsNot supported&anchor and *alias for reuse
StructureBraces {} and brackets []Indentation (2 spaces per level)
Trailing commaNot allowed (syntax error)N/A — no commas used
File extension.json.yaml or .yml
SpecRFC 8259 (2017)YAML 1.2 (2009)

When to use YAML vs JSON

Choose YAML for…
  • Kubernetes manifests and Helm values
  • GitHub Actions and GitLab CI pipelines
  • Docker Compose files
  • Ansible playbooks and inventories
  • Application config (Django, Rails, Spring)
  • OpenAPI / Swagger API specifications
  • Any file humans frequently read and edit
Choose JSON for…
  • REST API request and response bodies
  • Browser localStorage and sessionStorage
  • package.json, tsconfig.json
  • Database JSON/JSONB columns
  • Machine-to-machine data exchange
  • WebSocket and SSE message payloads
  • Any data parsed programmatically at high volume

The general rule: use YAML when humans write it, use JSON when machines exchange it. YAML's indentation sensitivity and its many boolean synonyms (yes/no/on/off) make it error-prone to generate programmatically, while JSON's strict syntax makes it trivial to serialize from any programming language.

YAML syntax reference

YAML has several core constructs that every developer working with configuration files needs to understand:

Scalars — plain, quoted, and block
# Plain string (no quotes needed)
name: Alice

# Quoted string (required when value contains : or #)
message: "Hello: world"

# Literal block scalar — preserves newlines
script: |
  echo "Starting deploy"
  npm install
  npm run build

# Folded block scalar — folds newlines into spaces
description: >
  This is a long description
  that spans multiple lines
  but will be one paragraph.

Single-quoted strings use '' to escape a literal apostrophe. Double-quoted strings support \n, \t, \\ escapes just like JSON.

Sequences (arrays)
# Block sequence
fruits:
  - apple
  - banana
  - cherry

# Flow sequence (JSON-style, valid YAML)
colors: [red, green, blue]

# Sequence of objects
users:
  - name: Alice
    role: admin
  - name: Bob
    role: viewer

Each - item is one array element. Objects inside an array are indented further. Flow sequences use JSON bracket syntax and are valid in YAML.

Mappings (objects)
# Block mapping
server:
  host: localhost
  port: 8080
  tls: true

# Flow mapping (JSON-style)
point: {x: 10, y: 20}

# Nested mappings
app:
  database:
    host: db.example.com
    port: 5432

Indentation defines nesting. Two spaces is the standard. Tabs cause parse errors — always use spaces.

Anchors and aliases — reusing values
# Define an anchor
defaults: &defaults
  replicas: 3
  env: production
  timeout: 30

# Merge with <<: *alias
web:
  <<: *defaults
  port: 80

api:
  <<: *defaults
  port: 3000
  replicas: 5  # override the anchored value

Anchors (&name) mark a node, aliases (*name) reuse it. The merge key (<<) copies all key-value pairs from the aliased mapping — think of it as YAML's object spread. Aliases are resolved to their values when converting to JSON.

Common YAML mistakes

Tabs instead of spaceskey:\n\t value: 123

YAML forbids tab characters for indentation. Use spaces only. Configure your editor to insert spaces when you press Tab in .yaml files.

Unquoted boolean-like stringscountry: NO # parsed as false!

The strings yes, no, true, false, on, off are parsed as booleans. Quote them: country: "NO". Norway's country code has caused real YAML bugs.

Duplicate keyshost: localhost\nhost: 127.0.0.1

YAML parsers may accept duplicate keys but behavior varies — some take the last value, others the first. Use unique keys or use an anchor/alias.

Missing space after colonkey:value # parse error

A key-value pair requires a space after the colon: key: value. Without the space, the entire string is treated as a plain scalar.

Inconsistent indentationparent:\n child: 1\n another: 2

All sibling keys at the same level must have the same indentation. Mixing 2-space and 3-space indent siblings causes parse errors.

Converting between formats in different languages

Python — PyYAML
import yaml, json

# JSON → YAML
with open('data.json') as f:
    data = json.load(f)
yaml_str = yaml.dump(data, default_flow_style=False, sort_keys=False)

# YAML → JSON
with open('config.yaml') as f:
    data = yaml.safe_load(f)  # use safe_load, not load!
json_str = json.dumps(data, indent=2)

Always use yaml.safe_load() instead of yaml.load() to prevent arbitrary code execution via malicious YAML files (a known security vulnerability in PyYAML).

Node.js — js-yaml
const yaml = require('js-yaml');
const fs = require('fs');

// JSON → YAML
const data = JSON.parse(fs.readFileSync('data.json', 'utf8'));
const yamlStr = yaml.dump(data);

// YAML → JSON
const yamlContent = fs.readFileSync('config.yaml', 'utf8');
const parsed = yaml.load(yamlContent);
const jsonStr = JSON.stringify(parsed, null, 2);

js-yaml is the most popular YAML library in the Node.js ecosystem. Install with: npm install js-yaml. It also provides a CLI: js-yaml input.yaml > output.json

Go — gopkg.in/yaml.v3
package main

import (
    "encoding/json"
    "gopkg.in/yaml.v3"
)

// YAML → JSON via intermediate struct
var data interface{}
yaml.Unmarshal(yamlBytes, &data)
jsonBytes, _ := json.MarshalIndent(data, "", "  ")

// JSON → YAML via intermediate struct
var obj interface{}
json.Unmarshal(jsonBytes, &obj)
yamlBytes, _ := yaml.Marshal(obj)

Go's encoding/json and yaml.v3 both work with interface{} as an intermediate. Note that yaml.v3 uses map[string]interface{} for objects, compatible with encoding/json.

YAML in CI/CD — practical examples

YAML configuration is central to modern DevOps workflows. Here's what real YAML usage looks like in common platforms:

GitHub Actions

Workflow files live in .github/workflows/. Each file defines triggers (on: push, pull_request), jobs with runs-on environments, and steps that either run shell commands or call reusable actions. The uses: keyword references an action; the with: mapping passes inputs.

Kubernetes

Every Kubernetes resource — Pod, Deployment, Service, ConfigMap, Ingress — is defined in YAML. The four mandatory fields are apiVersion, kind, metadata, and spec. kubectl apply -f manifest.yaml creates or updates the resource. Helm charts wrap these manifests in templates with {{ .Values.xxx }} placeholders.

Docker Compose

docker-compose.yml defines multi-container applications: service names, image references, port mappings, volume mounts, environment variables, and dependencies between services. The depends_on key controls startup order, while networks and volumes are declared at the top level and referenced by services.

OpenAPI / Swagger

API specifications in YAML describe endpoints (paths:), request parameters, request bodies, and response schemas. YAML's multi-line strings and anchors make OpenAPI specs more readable than JSON equivalents — anchors eliminate duplication of shared schemas across multiple endpoints.

FAQ

Common questions

What is YAML?

YAML (YAML Ain't Markup Language) is a human-friendly data serialization format. Unlike JSON, it uses indentation to express structure instead of brackets and braces, making it easier to read and write for configuration files. YAML is a superset of JSON — every valid JSON document is also valid YAML.

What is the difference between JSON and YAML?

JSON uses curly braces, square brackets, and quotation marks to define structure. YAML relies on indentation and colons, omitting most punctuation. YAML supports comments (lines starting with #), multi-line strings, and anchors/aliases for reusing values — none of which exist in JSON. JSON is better for APIs and data exchange; YAML is better for human-edited config files.

Is YAML a superset of JSON?

Yes — YAML 1.2 is a strict superset of JSON. Any valid JSON can be parsed by a YAML parser. However, YAML allows constructs that are not valid JSON (comments, unquoted strings, block scalars, anchors). When converting YAML to JSON, those YAML-only features must be stripped or converted.

Why does indentation matter in YAML?

YAML uses indentation (spaces only — never tabs) to express nesting and hierarchy. Two spaces per level is the convention. Mixing tabs and spaces causes parse errors. The indentation level determines whether a key belongs to the parent object or is a sibling.

When should I use YAML instead of JSON?

Use YAML for files that humans frequently edit: CI/CD pipeline configs (GitHub Actions, GitLab CI), Docker Compose, Kubernetes manifests, Ansible playbooks, and application settings. Use JSON for API payloads, localStorage, and machine-to-machine data exchange where performance and strict parsing matter more than readability.

Can YAML have comments?

Yes — YAML supports comments starting with #. Comments can appear on their own line or after a value. For example: port: 8080 # HTTP port. Comments are ignored by YAML parsers and are stripped when converting to JSON, since JSON has no comment syntax.

What are YAML anchors and aliases?

Anchors (&name) let you label a YAML node, and aliases (*name) let you reference it later. This avoids repetition in config files. For example: defaults: &defaults env: production replicas: 3 web: <<: *defaults port: 80. When converting to JSON, anchors and aliases are resolved into their final values.

Why do some strings need quotes in YAML?

Strings that look like other YAML types (numbers, booleans, null) must be quoted to be treated as strings. For example, "true", "null", "1.0", and "yes" are all interpreted as non-string scalars unless quoted. Strings containing colons, hashes, or brackets also need quotes to avoid parse errors.

Is my data safe when using this converter?

Yes. All conversion happens entirely in your browser using pure TypeScript/JavaScript. No data is sent to any server. The conversion logic runs locally — your configuration files, secrets, and API keys never leave your device.

More in Data & Format