YAML Advanced Features - Anchors, Aliases & Multiline

Anchors and Aliases

Anchors and aliases allow you to define reusable content and avoid repetition in your YAML files. This is particularly useful for large configuration files.

Basic Anchors and Aliases

# Define an anchor with &
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

# Use the anchor with *
development:
  <<: *defaults
  database: myapp_development

test:
  <<: *defaults
  database: myapp_test

production:
  <<: *defaults
  database: myapp_production
  host: prod-db.example.com

Anchors for Values

# Define reusable values
version: &version "2.1.0"
author: &author "John Doe"

# Use them throughout the file
app1:
  version: *version
  author: *author
  name: "My App 1"

app2:
  version: *version
  author: *author
  name: "My App 2"

Complex Anchors

# Define complex structures
database_config: &db_config
  adapter: postgresql
  encoding: unicode
  pool: 5
  timeout: 5000
  reconnect: true

# Use in multiple environments
development:
  database: myapp_dev
  <<: *db_config

test:
  database: myapp_test
  <<: *db_config
  pool: 1

production:
  database: myapp_prod
  <<: *db_config
  host: prod-db.example.com
  pool: 20

Multiline Strings

YAML provides several ways to handle multiline strings, each with different behaviors for line breaks and whitespace.

Literal Block Scalar (|)

# Preserves all line breaks and formatting
description: |
  This is a multiline string
  that preserves all line breaks
  and indentation exactly as written.
  
  Empty lines are also preserved.

# Common use cases
sql_query: |
  SELECT users.id, users.name, users.email
  FROM users
  WHERE users.active = true
  ORDER BY users.created_at DESC

email_template: |
  Dear {{name}},
  
  Thank you for your order #{{order_id}}.
  
  Best regards,
  The Team

Folded Block Scalar (>)

# Converts line breaks to spaces
summary: >
  This is a folded string
  that will be converted
  to a single line with spaces
  between words.

# Useful for long descriptions
product_description: >
  This amazing product combines cutting-edge technology
  with user-friendly design to deliver an exceptional
  experience that will exceed your expectations.

# Email content
email_body: >
  Hello {{customer_name}},
  
  Your order has been processed and will be shipped
  within 2-3 business days.
  
  Thank you for choosing us!

Indentation Control

# Strip leading whitespace
text: |-
  This text has
  no trailing newline

# Keep trailing newline
text: |+
  This text has
  a trailing newline

# Strip specific indentation
text: |2
    This text has
    indentation stripped
    to 2 spaces

# Example with code
python_code: |
  def hello_world():
      print("Hello, World!")
      return True

Flow Styles

Flow styles provide a more compact way to write YAML using JSON-like syntax with brackets and braces.

Flow Sequences (Arrays)

# Block style
fruits:
  - apple
  - banana
  - orange

# Flow style
fruits: [apple, banana, orange]

# Mixed types
mixed: [1, "hello", true, null]

# Nested flow sequences
matrix: [[1, 2, 3], [4, 5, 6], [7, 8, 9]]

Flow Mappings (Objects)

# Block style
person:
  name: John
  age: 30
  city: New York

# Flow style
person: {name: John, age: 30, city: New York}

# Nested flow mappings
config: {database: {host: localhost, port: 5432}, server: {port: 8080}}

# Complex nested structure
api_config: {
  base_url: "https://api.example.com",
  version: "v1",
  endpoints: {
    users: "/users",
    posts: "/posts",
    comments: "/comments"
  },
  auth: {
    type: "bearer",
    token: "your-token-here"
  }
}

Mixed Flow and Block Styles

# Mix flow and block styles
application:
  name: "My App"
  version: "1.0.0"
  features: [auth, logging, monitoring]
  database:
    host: localhost
    port: 5432
    options: {pool: 5, timeout: 30}
  servers: [
    {name: "web1", ip: "192.168.1.10"},
    {name: "web2", ip: "192.168.1.11"},
    {name: "db1", ip: "192.168.1.20"}
  ]

Tags and Type System

YAML supports a tag system that allows you to specify the type of data explicitly.

Built-in Tags

# String tags
name: !!str John Doe
description: !!str "A person's name"

# Integer tags
age: !!int 30
count: !!int 100

# Float tags
price: !!float 19.99
percentage: !!float 85.5

# Boolean tags
active: !!bool true
enabled: !!bool false

# Null tags
value: !!null null
empty: !!null ~

Sequence and Mapping Tags

# Sequence (array) tags
fruits: !!seq [apple, banana, orange]
numbers: !!seq [1, 2, 3, 4, 5]

# Mapping (object) tags
person: !!map {name: John, age: 30}
config: !!map {host: localhost, port: 8080}

# Ordered mapping
ordered_config: !!omap
  - first: value1
  - second: value2
  - third: value3

Custom Tags

# Custom tags (application-specific)
timestamp: !!timestamp 2023-12-25T10:30:00Z
binary_data: !!binary |
  R0lGODlhDAAMAIQAAP//9/X17unp5WZmZgAAAOfn515eXvPz7Y6OjuDg4J+fn5
  OTk6enp56enmlpaWNjY6Ojo4SEhP/++f/++f/++f/++f/++f/++f/++f/++f/+
  +f/++SH+Dk1hZGUgd2l0aCBHSU1QACwAAAAADAAMAAAFLCAgjoEwnuNAFOhpEMTR
  ighmSyCbUyJisM4zISWQEEvE8DArEISgBTS4dEQA7

# Date and time
birth_date: !!timestamp 1990-05-15
created_at: !!timestamp 2023-12-25T10:30:00Z

Document Separators

YAML supports multiple documents in a single file using document separators.

Multiple Documents

# First document
---
name: "Document 1"
version: "1.0"
description: "This is the first document"

# Second document
---
name: "Document 2"
version: "2.0"
description: "This is the second document"

# Third document
---
name: "Document 3"
version: "3.0"
description: "This is the third document"

Document with Directives

# YAML directive
%YAML 1.2
---
name: "YAML 1.2 Document"
version: "1.0"

# Tag directive
%TAG !yaml! tag:yaml.org,2002:
---
!yaml!str "This is a string with custom tag"
!yaml!int 42

Advanced Anchors and Merging

YAML provides powerful merging capabilities for combining data structures.

Merge Keys (<<)

# Define base configuration
defaults: &defaults
  adapter: postgresql
  encoding: unicode
  pool: 5
  timeout: 5000

# Merge with additional settings
development:
  <<: *defaults
  database: myapp_development
  host: localhost

production:
  <<: *defaults
  database: myapp_production
  host: prod-db.example.com
  pool: 20
  ssl: true

Multiple Merges

# Define multiple anchors
database_defaults: &db_defaults
  adapter: postgresql
  encoding: unicode

connection_defaults: &conn_defaults
  pool: 5
  timeout: 5000
  reconnect: true

# Merge multiple anchors
production:
  <<: [*db_defaults, *conn_defaults]
  database: myapp_production
  host: prod-db.example.com
  pool: 20

Nested Merges

# Complex nested structure
base_config: &base_config
  app:
    name: "My App"
    version: "1.0.0"
  database:
    adapter: postgresql
    encoding: unicode
  logging:
    level: info
    format: json

# Override specific nested values
development:
  <<: *base_config
  database:
    <<: *base_config.database
    host: localhost
    database: myapp_dev
  logging:
    level: debug

Real-World Examples

Here are some practical examples of advanced YAML features in real-world scenarios.

Docker Compose with Anchors

# Define common service configuration
x-common-variables: &common-variables
  POSTGRES_DB: myapp
  POSTGRES_USER: postgres
  POSTGRES_PASSWORD: password

# Define common service configuration
x-common-service: &common-service
  image: postgres:13
  environment: *common-variables
  volumes:
    - postgres_data:/var/lib/postgresql/data

services:
  db:
    <<: *common-service
    ports:
      - "5432:5432"

  db-test:
    <<: *common-service
    environment:
      <<: *common-variables
      POSTGRES_DB: myapp_test

volumes:
  postgres_data:

Kubernetes Configuration

# Define common metadata
common-labels: &common-labels
  app: my-app
  version: "1.0.0"
  environment: production

# Define common container spec
common-container: &common-container
  image: my-app:1.0.0
  ports:
    - containerPort: 8080
  resources:
    requests:
      memory: "64Mi"
      cpu: "250m"
    limits:
      memory: "128Mi"
      cpu: "500m"

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    <<: *common-labels
spec:
  replicas: 3
  selector:
    matchLabels:
      <<: *common-labels
  template:
    metadata:
      labels:
        <<: *common-labels
    spec:
      containers:
        - name: my-app
          <<: *common-container

Best Practices for Advanced Features

✅ Do's

Use anchors for repeated values: Define common configurations once
Keep anchors simple: Don't over-complicate anchor structures
Use meaningful anchor names: Make them descriptive and clear
Prefer block style for readability: Use flow style only when appropriate
Document complex structures: Add comments for complex anchor usage

⚠️ Don'ts

Don't overuse anchors: They can make simple files complex
Don't create circular references: Anchors referencing each other
Don't mix flow and block unnecessarily: Keep styles consistent
Don't use custom tags without documentation: Explain their purpose
Don't create deeply nested merges: Keep structures manageable

Practice Exercises

Test your advanced YAML skills with these exercises:

Exercise 1: Configuration Management

Create a configuration file for a multi-environment application using anchors and aliases.

Show Solution

# Base configuration
base_config: &base_config
  app:
    name: "My Application"
    version: "2.1.0"
  database:
    adapter: postgresql
    encoding: unicode
    pool: 5
  logging:
    level: info
    format: json

# Environment-specific configurations
development:
  <<: *base_config
  database:
    <<: *base_config.database
    host: localhost
    database: myapp_dev
  logging:
    level: debug

production:
  <<: *base_config
  database:
    <<: *base_config.database
    host: prod-db.example.com
    database: myapp_prod
    pool: 20
    ssl: true

Exercise 2: API Documentation

Create an API documentation file using multiline strings and complex structures.

Show Solution

api:
  name: "User Management API"
  version: "v1.2.0"
  description: |
    This API provides comprehensive user management functionality
    including user registration, authentication, profile management,
    and role-based access control.
  
  base_url: "https://api.example.com/v1"
  
  endpoints:
    users:
      list: |
        GET /users
        Returns a paginated list of all users
        with optional filtering and sorting.
      
      create: |
        POST /users
        Creates a new user account with the provided
        information and returns the user details.
      
      get: |
        GET /users/{id}
        Retrieves a specific user by ID.
      
      update: |
        PUT /users/{id}
        Updates an existing user's information.
      
      delete: |
        DELETE /users/{id}
        Soft deletes a user account.