YAML to JSON Converter: Parse YAML Online — Syntax Guide & Error Fixes

Last updated: June 2025 · 13 min read

YAML is everywhere in modern development — Docker Compose, Kubernetes, GitHub Actions, CI/CD pipelines, and countless application config files. But when you need to process YAML data programmatically, convert it for an API, or debug a configuration issue, converting it to JSON is often the fastest path forward.

This guide provides a complete YAML syntax reference, covers the most common parsing errors (and how to fix them), and explains when and how to convert YAML to JSON effectively.

YAML Syntax Quick Reference

Basic Structure

YAML uses indentation to define hierarchical structure. Each indentation level (typically 2 spaces) represents a nesting level. Keys and values are separated by a colon followed by a space.

# Basic key-value pairs
name: MyApp
version: 1.0.0
description: A sample application

# Nested objects (indentation = nesting)
database:
  host: localhost
  port: 5432
  name: production

# Lists (use hyphen + space)
features:
  - authentication
  - logging
  - caching

Data Types

Multi-line Strings

YAML has powerful multi-line string support using block scalars:

# Literal block (|) — preserves newlines exactly
description: |
  Line one
  Line two
  Line three

# Folded block (>) — converts single newlines to spaces
summary: >
  This is a long sentence that
  will be folded into a single
  line in the output.

# Strip trailing newline (|- or >-)
script: |-
  #!/bin/bash
  echo "hello"

# Keep trailing newlines (|+ or >+)
output: |+

  Two blank lines follow

Anchors and Aliases

YAML's anchor/alias system lets you define content once and reference it multiple times:

# Define an anchor with &
defaults: &defaults
  timeout: 30
  retries: 3

# Reference with *
service_a:
  <<: *defaults    # Merge defaults
  host: api-a.com

service_b:
  <<: *defaults
  host: api-b.com
  timeout: 60      # Override specific key

Advanced Features

# Tags (explicit types)
port: !!int "8080"        # Force integer type
is_active: !!bool "true"  # Force boolean type

# Document separator
---
document: 1
---
document: 2

# Complex keys (quoted)
"user@example.com":
  role: admin

# Flow vs Block style
# Block (default, readable):
servers:
  - name: web1
    ip: 10.0.0.1
  - name: web2
    ip: 10.0.0.2

# Flow (compact, JSON-like):
servers: [{name: web1, ip: 10.0.0.1}, {name: web2, ip: 10.0.0.2}]

Common YAML Errors and How to Fix Them

# ❌ Error
time: 12:30:00
url: https://example.com:8080

# ✅ Fixed
time: "12:30:00"
url: "https://example.com:8080"

# ❌ Error (inconsistent indentation)
server:
  host: localhost
   port: 8080    # Extra space!

# ✅ Fixed
server:
  host: localhost
  port: 8080

# ❌ Error
pattern: [a-z]+
comment: This # is not a comment

# ✅ Fixed
pattern: "[a-z]+"
comment: "This # is not a comment"

%YAML 1.2
---
# Content here

# ❌ Error (tabs used)
server:
	host: localhost

# ✅ Fixed (2 spaces)
server:
  host: localhost

YAML Type Coercion Gotchas

YAML's automatic type detection is convenient but can cause unexpected behavior. Here are the most common surprises:

When to Convert YAML to JSON

API Integration

Most REST APIs expect JSON request bodies. If your configuration or data is in YAML, converting to JSON is necessary before sending API requests.

Debugging

When a YAML file isn't behaving as expected, converting it to JSON reveals exactly how the parser interpreted your data — types, structure, and any surprises from automatic type coercion.

Data Processing Pipelines

Many data processing tools work with JSON natively. Converting YAML input to JSON at the pipeline entry point simplifies downstream processing.

Language Interoperability

While most languages have YAML parsers, JSON parsing is universally fast and reliable. Converting YAML to JSON before passing data between services eliminates parser compatibility issues.

Schema Validation

JSON Schema is more mature and widely supported than YAML schema validation. Converting to JSON lets you validate against existing JSON Schemas.

YAML Best Practices

1. Use 2-space indentation consistently. Never mix tabs and spaces. Configure your editor to insert spaces for Tab key.
2. Quote strings that look like booleans, numbers, or dates. This prevents type coercion surprises.
3. Use comments liberally. YAML's comment support is one of its biggest advantages over JSON.
4. Keep files under 1000 lines. If your YAML file is growing too large, split it into multiple files using anchors and aliases.
5. Validate with yamllint. Install yamllint and run it in your CI/CD pipeline to catch errors early.
6. Prefer block style over flow style. Block style (with indentation) is more readable. Reserve flow style for simple, single-line values.
7. Use explicit document markers. Start multi-document files with --- and separate documents clearly.
8. Avoid YAML 1.1-specific features. Stick to YAML 1.2 for maximum parser compatibility.

Converting YAML to JSON: What Happens Under the Hood

When you convert YAML to JSON, several transformations occur:

1. Parsing: The YAML parser reads the text and builds an in-memory data structure (usually a tree of maps and arrays).
2. Type resolution: Each value is assigned a type based on YAML's rules (string, integer, float, boolean, null).
3. Serialization: The data structure is serialized to JSON format with proper quoting, brackets, and commas.

Key differences in the output:

• Comments are removed (JSON doesn't support them).
• Anchors and aliases are resolved (the referenced content is duplicated in the JSON output).
• Multi-line strings become single-line strings with \n escape sequences.
• Tags and type hints are lost — only the resolved value remains.
• Document separators (---) are not represented in JSON.

Frequently Asked Questions

How do I fix "mapping values are not allowed here" in YAML?

This error means a colon (:) in your YAML is being interpreted as a key-value separator when it shouldn't be. Fix by quoting the string containing the colon, or ensuring the colon after a key has a space after it.

Why does my YAML file fail to parse?

Common reasons: inconsistent indentation (mixing tabs and spaces), unquoted special characters, incorrect list syntax, or invalid YAML version. Use a linter like yamllint to identify the exact issue.

Does YAML support tabs for indentation?

No. YAML specification forbids using tabs for indentation — you must use spaces. Most YAML parsers will reject files with tabs. Use 2 spaces per indentation level as the standard convention.

How do I write a multi-line string in YAML?

Use the pipe (|) character for literal newlines (preserves line breaks) or greater-than (>) for folded newlines (converts single newlines to spaces). Add a chomping indicator (+ or -) to control trailing newlines.

What is the difference between YAML and JSON?

YAML uses indentation for structure and supports comments, anchors, and multi-line strings. JSON uses braces/brackets and is more strict. YAML is a superset of JSON — all valid JSON is valid YAML.

Conclusion

YAML's flexibility makes it powerful for configuration, but that same flexibility can lead to parsing errors and type coercion surprises. Converting YAML to JSON is an invaluable debugging technique that reveals exactly how your YAML is being interpreted.

Our free YAML to JSON converter runs entirely in your browser — paste your YAML, get instant JSON output with proper formatting. It handles anchors, aliases, multi-line strings, and type coercion correctly, so you can focus on your work instead of fighting with parsers.