Reference

YAML Reference Guide

Everything you need to know about YAML syntax. Quick reference covering comments, data types, multiline strings, anchors, and common mistakes in OpenAPI specifications.

Try Specway FreeAPI Design Guide
8 min readAll LevelsLast updated: March 2026

Basic Syntax

Key-value pairs, indentation, and structure.

# YAML uses indentation (spaces, never tabs)
name: My API
version: 1.0.0
description: A sample API

# Nested objects use indentation
server:
  host: api.example.com
  port: 443
  protocol: https

# Inline objects (flow style)
server: { host: api.example.com, port: 443 }

Comments in YAML

YAML only supports single-line comments with the # character.

# This is a full-line comment
name: My API  # This is an inline comment

# Multi-line comments require # on each line
# There is no block comment syntax in YAML.
# Each line must start with #.

# Comments are great for documenting your OpenAPI spec
paths:
  /users:
    get:
      # This endpoint requires authentication
      summary: List all users
      # TODO: Add pagination parameters
      parameters: []

Data Types

YAML auto-detects types. Use quotes to force strings.

# Strings (quotes optional for simple values)
name: Jane Smith
quoted: "true"           # String, not boolean
single: 'contains "quotes"'

# Numbers
count: 42                # Integer
price: 19.99             # Float
hex: 0xFF                # Hexadecimal
octal: 0o77              # Octal
scientific: 1.2e+5       # Scientific notation

# Booleans (case-insensitive)
enabled: true
active: True
disabled: false
legacy: False

# Null
value: null
also_null: ~
empty_null:              # Empty value = null

# Dates
created: 2025-01-15
timestamp: 2025-01-15T10:30:00Z

Lists (Sequences)

Arrays in YAML use a dash prefix or inline brackets.

# Block style (most common in OpenAPI)
tags:
  - users
  - authentication
  - admin

# Inline style (flow)
tags: [users, authentication, admin]

# List of objects
servers:
  - url: https://api.example.com
    description: Production
  - url: https://staging.example.com
    description: Staging

# Nested lists
matrix:
  - [1, 2, 3]
  - [4, 5, 6]

Multiline Strings

YAML has multiple ways to handle long text blocks.

# Literal block (|) - preserves newlines
description: |
  This is a multi-line description.
  Each line break is preserved exactly.

  Blank lines create paragraphs.

# Folded block (>) - joins lines with spaces
description: >
  This is a long description that
  will be folded into a single line
  with spaces between each segment.

# Strip trailing newline (|-, >-)
description: |-
  No trailing newline
  after this block

# Keep trailing newlines (|+, >+)
description: |+
  Trailing newlines
  are preserved

# In OpenAPI, folded is common for descriptions
paths:
  /users:
    get:
      description: >
        Returns a paginated list of all users
        in the organization. Requires admin
        authentication.

Anchors & Aliases

Reuse YAML blocks to keep your specs DRY.

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

# Reference it with *
production:
  <<: *default_settings  # Merge anchor
  url: https://api.example.com

staging:
  <<: *default_settings
  url: https://staging.example.com
  timeout: 60  # Override a value

# In OpenAPI, use $ref instead of anchors
# Anchors work but $ref is the standard
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

YAML vs JSON Comparison

YAML is a superset of JSON. Every valid JSON file is also valid YAML. Here is how they compare.

FeatureYAMLJSON
CommentsSupported (#)Not supported
ReadabilityMore readable (indentation-based)More verbose (braces, quotes)
Data typesAuto-detected (strings, numbers, booleans, dates)Explicit (everything in quotes except numbers/booleans)
Parsing speedSlower (more complex parser)Faster (simpler grammar)
Multiline stringsNative support (| and >)Must use \n escapes
Browser supportRequires libraryNative JSON.parse()
File sizeSmaller (no braces/quotes)Larger (required syntax chars)
Anchors/reuseBuilt-in (&, *)Not supported ($ref is OpenAPI-specific)
StrictnessFlexible (can cause ambiguity)Strict (fewer surprises)

Common YAML Mistakes in OpenAPI Specs

These are the most common YAML errors that break OpenAPI specifications. Learn to spot and avoid them.

Using tabs instead of spaces

Wrong
host:\tapi.example.com  # Tab character
Correct
host:  api.example.com  # Two spaces

YAML strictly requires spaces for indentation. Tabs will cause parse errors. Configure your editor to use spaces.

Unquoted special values

Wrong
country: NO    # Parsed as boolean false!
version: 1.0   # Parsed as float, not string
Correct
country: "NO"  # String
version: "1.0" # String

YAML auto-detects types. "NO", "yes", "true", "on", "off" become booleans. Version numbers like 1.0 become floats. Always quote values that look like booleans or numbers but should be strings.

Inconsistent indentation

Wrong
paths:
  /users:
      get:        # 6 spaces
    post:       # 4 spaces (inconsistent)
Correct
paths:
  /users:
    get:          # 4 spaces
    post:         # 4 spaces (consistent)

Within the same level, all items must use the same indentation. Mixing indentation depths causes parse errors.

Missing space after colon

Wrong
name:value     # No space after colon
Correct
name: value    # Space after colon required

YAML requires a space after the colon in key-value pairs. Without it, the entire string is treated as the key.

Related Guides

API Design Guide

Best practices for designing REST APIs

OpenAPI Import

Auto-generate docs from your OpenAPI specification

Frequently Asked Questions

Common questions about YAML syntax.

Write Your OpenAPI Spec, Publish Beautiful Docs

Import your YAML or JSON OpenAPI spec into Specway and publish interactive API documentation in minutes.

Start Publishing FreeView Pricing