YAML Syntax Guide — Format, Rules, and Examples

YAML (YAML Ain't Markup Language) is a human-readable data format that uses indentation to represent structure. A YAML file stores the same information as JSON or XML but in a format designed to be easy to read and edit by humans. It is the default config format for Kubernetes, Docker Compose, GitHub Actions, Ansible, and dozens of other tools.

This guide covers every YAML syntax rule you need to write and read YAML files confidently: indentation, data types, strings, arrays, objects, multiline values, anchors, and aliases. Each rule includes a working example plus the equivalent JSON so you can see exactly what each syntax produces.

YAML Indentation Rules (The Most Important Concept)

Indentation is how YAML defines structure. The rules are strict:

• Spaces only — tabs are never allowed, not even a single tab. A tab character anywhere will cause a parse error.
• Consistent levels — every child key must be indented the same number of spaces relative to its parent.
• 2 spaces per level — the universal convention. Some tools use 4. Choose one and stick to it.

# Valid YAML
server:
  host: localhost
  port: 8080
  database:
    name: mydb
    user: admin

The above maps to this JSON:

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "database": {
      "name": "mydb",
      "user": "admin"
    }
  }
}

If any line is indented with a tab or by the wrong number of spaces, the converter will report an error with a line number. Fix by converting all tabs to spaces and aligning sibling keys to the same column.

YAML Data Types — Strings, Numbers, Booleans, Null

YAML automatically detects data types from the value format. You rarely need to annotate types explicitly.

Strings:

name: Alice          # plain string — no quotes needed
city: "New York"     # quoted string — use when value contains special chars
message: 'It''s fine' # single-quoted — literal apostrophe needs doubling

Numbers:

age: 30              # integer
price: 19.99         # float
hex: 0xFF            # hexadecimal (YAML 1.1)

Booleans:

enabled: true        # boolean true
debug: false         # boolean false

In YAML 1.1 (older), the words yes, no, on, off also became booleans. In YAML 1.2 (current), only true and false are booleans. If you use yes or no as string values, quote them to be safe: answer: "yes".

Null:

middle_name: null    # explicit null
nickname:            # empty value — also null

To verify how your YAML will parse, paste it into the YAML to JSON converter. The JSON output shows exactly what type each value became after parsing.

YAML Arrays — Block and Flow Style

Arrays in YAML have two syntaxes: block style (one item per line) and flow style (inline).

Block style — most readable:

fruits:
  - apple
  - banana
  - cherry

Converts to: {"fruits": ["apple", "banana", "cherry"]}

Flow style — compact:

fruits: [apple, banana, cherry]

Same result, just written on one line. Use flow style for short arrays; use block style for longer lists.

Array of objects:

users:
  - name: Alice
    role: admin
  - name: Bob
    role: viewer

Each - starts a new object in the array. The keys under each dash belong to that object. The dash-space (- ) counts as two characters of indentation — the keys under it align at the same level as the dash plus two spaces.

YAML Objects — Key-Value Pairs and Nested Maps

A YAML mapping is a set of key-value pairs. Keys and values are separated by a colon followed by a space.

database:
  host: 127.0.0.1
  port: 5432
  credentials:
    user: admin
    password: secret

The colon-space separator is required. host:127.0.0.1 (no space) will be treated as a plain string, not a key-value pair.

Inline (flow) style:

database: {host: 127.0.0.1, port: 5432}

Same data, compact syntax. Both styles can be mixed in the same file.

Keys with special characters: If a key contains a colon, space, or other special character, quote the key:

"my:key": value
"key with spaces": value

Sell Custom Apparel — We Handle Printing & Free Shipping

YAML Strings — When Quotes Are Required

Most strings in YAML do not need quotes. But certain characters force quoting to avoid misparse:

Character	Problem	Fix
: followed by space	Looks like a key-value separator	Quote the value: "host: localhost"
# anywhere	Starts a comment	Quote the string: "color #ff0000"
Leading { or [	Looks like flow-style map/array	Quote: "{not a map}"
yes / no / true / false	Parsed as boolean (YAML 1.1)	Quote: "yes"
null / ~	Parsed as null	Quote: "null"
Leading 0 in number	May be parsed as octal	Quote: "007"

Double-quoted strings support escape sequences: (newline), (tab), " (quote).

Single-quoted strings are literal — no escape sequences. A literal apostrophe is represented by doubling it: 'it''s'.

When in doubt, quote it. Quoted strings never mis-parse.

YAML Multiline Strings — Literal and Folded Block Scalars

YAML provides two special syntaxes for multiline string values.

Literal block (|) — preserves newlines:

message: |
  Hello, world.
  This is line two.
  This is line three.

The value becomes a string with real newlines: "Hello, world. This is line two. This is line three. ". Use this for scripts, code blocks, or any content where line breaks matter.

Folded block (>) — folds newlines to spaces:

description: >
  This is a long description
  that wraps across multiple lines
  but will be joined with spaces.

The value becomes: "This is a long description that wraps across multiple lines but will be joined with spaces. ". Use this for long prose where you want to wrap for readability in the file but receive a single paragraph string.

Chomping indicators: By default, a single trailing newline is kept. Add |- to strip it, or |+ to keep all trailing newlines.

YAML Anchors and Aliases — Reuse Values Without Repeating

YAML anchors let you define a value once and reference it multiple times — like variables.

defaults: &defaults
  timeout: 30
  retries: 3
  log_level: info

production:
  <<: *defaults
  host: prod.example.com

staging:
  <<: *defaults
  host: staging.example.com

&defaults defines the anchor. *defaults is the alias that references it. <<: is the merge key — it expands the referenced map into the current object, then any local keys override it.

The JSON equivalent:

{
  "defaults": {"timeout": 30, "retries": 3, "log_level": "info"},
  "production": {"timeout": 30, "retries": 3, "log_level": "info", "host": "prod.example.com"},
  "staging": {"timeout": 30, "retries": 3, "log_level": "info", "host": "staging.example.com"}
}

To see how your anchors expand, paste the YAML into the YAML to JSON converter. The JSON output shows the fully-resolved values with all aliases expanded.

YAML Comments — Inline and Block

YAML supports comments using the # character. Everything from # to the end of the line is ignored by the parser.

# This is a full-line comment
server:
  host: localhost  # inline comment
  port: 8080       # default port

Comments are stripped when converting to JSON — JSON does not support comments. This is one reason YAML is preferred over JSON for config files that humans edit frequently.

Common mistake: A # inside a quoted string is not a comment — it is a literal character. Only unquoted # preceded by a space (or at line start) is a comment.

Convert YAML to JSON to Verify Your Syntax

The fastest way to verify that your YAML is syntactically correct is to convert it to JSON. A valid conversion proves valid syntax. Any errors in the YAML appear as error messages with line numbers before the conversion runs.

Use the free YAML to JSON converter:

1. Paste your YAML into the input panel.
2. Click Convert.
3. If the output panel shows JSON, the syntax is valid.
4. If the error panel shows a message, fix the indicated line and try again.

This is especially useful when editing Kubernetes manifests, Docker Compose files, GitHub Actions workflows, or any config file where a syntax error causes a runtime failure.

Frequently Asked Questions

Does YAML allow tabs for indentation?

No. YAML strictly forbids tab characters for indentation. Every level of indentation must use spaces. If your YAML file uses tabs, you will get a parse error. Most editors have a "convert tabs to spaces" setting — enable it for YAML files.

What is the difference between single quotes and double quotes in YAML?

Double-quoted strings support escape sequences like \n (newline), \t (tab), and \\ (backslash). Single-quoted strings are fully literal — no escape processing. A literal single quote inside a single-quoted string is written as two apostrophes: 'it''s'.

How do I write a YAML value that starts with a colon?

Quote the value. For example: value: ":8080". Without quotes, the colon-space would be interpreted as a key-value separator and cause a parse error.

Is YAML a superset of JSON?

YAML 1.2 is a superset of JSON — every valid JSON document is also valid YAML 1.2. This means you can paste JSON directly into a YAML config and it will parse correctly. YAML 1.1 has some edge-case differences with special values like yes/no/on/off.

How do I check if my YAML is valid without installing anything?

Paste it into a browser-based YAML to JSON converter. If the conversion succeeds, the YAML is syntactically valid. If it fails, the error message shows the line and column where the problem is. No installation needed.