YAML Syntax Explained

YAML is one of the most popular formats for writing configuration files. It is designed to be easy for humans to read while remaining simple for software to parse. Today YAML is widely used in Kubernetes, Docker Compose, GitHub Actions, CI/CD pipelines and many other development tools.

Unlike JSON, YAML relies primarily on indentation rather than braces and commas. Understanding its syntax is essential because even a small formatting mistake can completely change the structure of a document.

Basic Structure

A YAML document is composed of mappings (key-value pairs), sequences (lists) and scalar values such as strings, numbers and booleans.

name: Alice
age: 30
admin: true

Each line defines a key followed by a colon and its corresponding value.

Key-Value Pairs

The most fundamental building block in YAML is the mapping, commonly called a key-value pair.

host: localhost
port: 8080

Every key maps to exactly one value, which may itself be another object or a list.

Indentation

Indentation defines the hierarchy of a YAML document. Child elements must be indented consistently beneath their parent.

database:
  host: localhost
  port: 5432

Both 'host' and 'port' belong to the 'database' object because they are indented by the same amount.

Spaces vs Tabs

YAML files should use spaces for indentation. Although some editors insert tabs automatically, many YAML parsers reject them.

Nested Objects

Mappings can contain other mappings, allowing complex hierarchical structures.

server:
  host: localhost
  port: 8080
  ssl:
    enabled: true
    certificate: cert.pem

Each additional indentation level creates another level in the resulting object hierarchy.

Lists

Lists, also called sequences, are represented using hyphens.

languages:
  - JavaScript
  - TypeScript
  - Python

Each hyphen introduces a new item in the sequence.

Lists of Objects

Sequence items may themselves contain mappings, making it easy to represent collections of structured objects.

users:
  - name: Alice
    role: Admin

  - name: Bob
    role: Editor

This structure is commonly used for users, servers, containers and deployment configurations.

Scalar Values

Scalar values are individual values such as strings, numbers, booleans or null values.

Quoted and Unquoted Strings

Many strings can be written without quotation marks, making YAML cleaner than JSON.

title: My Application

Quotation marks become necessary when values contain special characters, leading or trailing spaces or characters that could otherwise be interpreted as another data type.

version: "1.0"
message: "Hello: World"

Multiline Strings

YAML provides convenient syntax for writing long blocks of text without escaping newline characters. Two operators are commonly used: the pipe (|) preserves line breaks, while the greater-than sign (>) folds multiple lines into a single paragraph.

message: |
  Welcome to our application.
  Enjoy your stay!

Using the pipe keeps every line exactly as written.

description: >
  This text
  will become
  one single paragraph.

The folded style is useful for long descriptions that should be displayed as a single line after parsing.

Comments

Unlike JSON, YAML supports comments. Everything following the # character on a line is ignored by the parser.

# Application settings
server:
  port: 8080

Comments make configuration files easier to understand and maintain, especially in collaborative projects.

Multiple Documents

A single YAML file can contain multiple documents separated by three hyphens.

---
name: Development

---
name: Production

This feature is commonly used in Kubernetes manifests where several resources are stored in one file.

Anchors and Aliases

YAML allows repeated values to be reused through anchors and aliases, reducing duplication in large configuration files.

defaults: &defaults
  retries: 3
  timeout: 30

development:
  <<: *defaults

production:
  <<: *defaults

This capability is unique to YAML and is frequently used in deployment and infrastructure configurations.

Common YAML Syntax Errors

• Using tabs instead of spaces.
• Incorrect indentation levels.
• Missing spaces after colons.
• Mixing list items and mappings incorrectly.
• Forgetting quotation marks around special characters when required.

Best Practices

• Use consistent indentation throughout the file.
• Prefer two spaces per indentation level.
• Use meaningful key names.
• Keep nesting reasonably shallow.
• Validate files before deploying them.
• Format YAML automatically to maintain consistency.

Using YAML Tools

As YAML files grow larger, formatting and validation tools become increasingly valuable. A formatter applies consistent indentation, a validator detects syntax errors, a tree viewer helps visualize nested structures, and merge or sorting tools simplify maintenance of large configuration files.

Frequently Asked Questions

Conclusion

YAML syntax is simple once you understand its core principles: consistent indentation, mappings, lists and scalar values. Its readability makes it an excellent choice for configuration files, while features such as comments, multiline strings and anchors provide flexibility beyond JSON. Using a YAML Formatter, Validator, Tree Viewer, Key Sorter and Merge Tool helps keep even large YAML documents clean, valid and easy to maintain.