YAML Best Practices

Learn professional guidelines for writing clean, maintainable, and efficient YAML files.

Formatting and Style Guidelines

Consistent formatting makes YAML files easier to read, maintain, and debug. Follow these guidelines for professional YAML files.

✅ Indentation Best Practices

  • Use 2 spaces per indentation level - Most common and readable
  • Never mix tabs and spaces - Choose one and stick to it
  • Be consistent throughout the file - Don't change indentation style
  • Use a YAML linter - Automatically check for indentation issues

Good Indentation

# ✅ Good - consistent 2-space indentation
database:
  host: localhost
  port: 5432
  credentials:
    username: admin
    password: secret
  options:
    pool: 5
    timeout: 30

Bad Indentation

# ❌ Bad - inconsistent indentation
database:
    host: localhost
  port: 5432
    credentials:
      username: admin
        password: secret

Naming Conventions

Use clear, descriptive names that follow consistent conventions throughout your YAML files.

✅ Naming Best Practices

  • Use snake_case for keys - Most common in YAML
  • Use descriptive names - Avoid abbreviations when possible
  • Be consistent with naming style - Don't mix camelCase and snake_case
  • Use meaningful prefixes - Group related settings

Good Naming

# ✅ Good - clear, descriptive names
application:
  name: "My Application"
  version: "2.1.0"
  environment: "production"

database_config:
  host: "db.example.com"
  port: 5432
  connection_timeout: 30
  max_connections: 100

api_settings:
  base_url: "https://api.example.com"
  rate_limit: 1000
  timeout_seconds: 30

Bad Naming

# ❌ Bad - unclear, inconsistent names
app:
  n: "My Application"  # Too short
  v: "2.1.0"           # Abbreviation
  env: "prod"          # Abbreviation

db:                    # Too short
  h: "db.example.com"  # Abbreviation
  p: 5432              # Abbreviation
  ct: 30               # Abbreviation

api:                   # Inconsistent with db_config above
  url: "https://api.example.com"
  limit: 1000
  timeout: 30

String Handling

Proper string handling prevents common YAML parsing issues and improves readability.

✅ String Best Practices

  • Quote strings with special characters - Colons, quotes, etc.
  • Use consistent quoting style - Prefer double quotes
  • Quote values that look like other types - Dates, numbers, booleans
  • Use multiline strings for long text - Better readability

Good String Handling

# ✅ Good - proper string quoting
user:
  name: "John Doe"
  email: "john@example.com"
  description: "Software developer with 5 years experience"
  birth_date: "1990-05-15"  # Quote dates
  phone: "555-1234"         # Quote phone numbers
  status: "active"          # Quote status values

# Multiline strings for long text
error_message: |
  An error occurred while processing your request.
  Please check your input and try again.
  If the problem persists, contact support.

Bad String Handling

# ❌ Bad - unquoted special values
user:
  name: John Doe
  email: john@example.com
  description: Software developer with 5 years experience
  birth_date: 1990-05-15    # Looks like date, should be quoted
  phone: 555-1234           # Looks like number, should be quoted
  status: active            # Looks like boolean, should be quoted

# Long text without proper formatting
error_message: An error occurred while processing your request. Please check your input and try again. If the problem persists, contact support.

Comments and Documentation

Well-documented YAML files are easier to understand and maintain. Use comments strategically.

✅ Comment Best Practices

  • Document complex configurations - Explain non-obvious settings
  • Use section headers - Group related settings
  • Document default values - Note when values differ from defaults
  • Keep comments up to date - Remove outdated comments

Good Documentation

# Application Configuration
# This file contains all application settings
# Last updated: 2024-01-15

application:
  name: "My Application"
  version: "2.1.0"
  environment: "production"

# Database Configuration
# PostgreSQL database settings
database:
  host: "db.example.com"
  port: 5432
  name: "myapp_production"
  # Connection pool settings
  pool:
    min: 5      # Minimum connections
    max: 20     # Maximum connections
    timeout: 30 # Connection timeout in seconds

# API Configuration
api:
  base_url: "https://api.example.com"
  # Rate limiting (requests per minute)
  rate_limit: 1000
  # Request timeout in seconds
  timeout: 30
  # Enable API versioning
  versioning: true

Bad Documentation

# Bad - no comments or documentation
app:
  name: "My Application"
  version: "2.1.0"
  env: "prod"

db:
  host: "db.example.com"
  port: 5432
  name: "myapp_prod"
  pool: 20
  timeout: 30

api:
  url: "https://api.example.com"
  limit: 1000
  timeout: 30
  versioning: true

Structure and Organization

Well-organized YAML files are easier to navigate and maintain. Follow logical grouping principles.

✅ Structure Best Practices

  • Group related settings together - Database, API, logging, etc.
  • Use consistent hierarchy - Don't mix different organizational patterns
  • Keep nesting levels reasonable - Avoid deep nesting (max 4-5 levels)
  • Use anchors for repeated values - DRY principle

Good Structure

# Application metadata
application:
  name: "My Application"
  version: "2.1.0"
  environment: "production"

# Database configuration
database:
  host: "db.example.com"
  port: 5432
  name: "myapp_production"
  credentials:
    username: "admin"
    password: "secret"
  options:
    pool: 20
    timeout: 30
    ssl: true

# API configuration
api:
  base_url: "https://api.example.com"
  version: "v1"
  rate_limit: 1000
  timeout: 30
  endpoints:
    users: "/users"
    posts: "/posts"
    comments: "/comments"

# Logging configuration
logging:
  level: "info"
  format: "json"
  outputs:
    - console
    - file
  file:
    path: "/var/log/app.log"
    max_size: "100MB"
    max_files: 5

Bad Structure

# Bad - mixed organization, deep nesting
app:
  name: "My Application"
  version: "2.1.0"
  env: "prod"
  db:
    host: "db.example.com"
    port: 5432
    name: "myapp_prod"
    creds:
      user: "admin"
      pass: "secret"
      pool: 20
      timeout: 30
      ssl: true
    api:
      url: "https://api.example.com"
      ver: "v1"
      limit: 1000
      timeout: 30
      endpoints:
        users: "/users"
        posts: "/posts"
        comments: "/comments"
      logging:
        level: "info"
        format: "json"
        outputs: ["console", "file"]
        file:
          path: "/var/log/app.log"
          max_size: "100MB"
          max_files: 5

Performance Considerations

Optimize your YAML files for better performance and faster parsing.

✅ Performance Best Practices

  • Use anchors for repeated values - Reduces file size
  • Avoid deeply nested structures - Slower to parse
  • Use flow style for simple structures - Faster parsing
  • Minimize file size - Remove unnecessary whitespace

Performance Optimized

# Use anchors for repeated values
defaults: &defaults
  adapter: postgresql
  encoding: unicode
  pool: 5
  timeout: 5000

# Use flow style for simple structures
environments:
  development: {<<: *defaults, database: myapp_dev, host: localhost}
  test: {<<: *defaults, database: myapp_test, host: localhost}
  production: {<<: *defaults, database: myapp_prod, host: prod-db.example.com}

# Keep nesting shallow
config:
  app: {name: "My App", version: "2.1.0"}
  db: {host: "localhost", port: 5432}
  api: {url: "https://api.example.com", timeout: 30}

Common Pitfalls to Avoid

Learn about common YAML mistakes and how to avoid them.

⚠️ Common Pitfalls

  • Inconsistent indentation - Mixing tabs and spaces
  • Unquoted special values - Dates, numbers, booleans
  • Missing colons - Forgetting : after keys
  • Wrong list syntax - Using [] instead of -
  • Circular references - Anchors referencing each other
  • Overly complex structures - Hard to read and maintain

Common Mistakes

# ❌ Wrong - missing colon
name John Doe

# ❌ Wrong - inconsistent indentation
person:
  name: John
    age: 30

# ❌ Wrong - unquoted special values
date: 2023-12-25
phone: 555-1234
status: active

# ❌ Wrong - using brackets for lists
fruits: [apple, banana, orange]

# ❌ Wrong - circular reference
user1: &user1
  name: John
  friend: *user2
user2: &user2
  name: Jane
  friend: *user1

Corrected Version

# ✅ Correct - proper colon
name: John Doe

# ✅ Correct - consistent indentation
person:
  name: John
  age: 30

# ✅ Correct - quoted special values
date: "2023-12-25"
phone: "555-1234"
status: "active"

# ✅ Correct - proper list syntax
fruits:
  - apple
  - banana
  - orange

# ✅ Correct - no circular references
user1:
  name: John
  friend: "Jane"
user2:
  name: Jane
  friend: "John"

Validation and Testing

Always validate your YAML files to catch errors early and ensure they work as expected.

✅ Validation Best Practices

  • Use YAML validators - Check syntax before deployment
  • Test with your application - Ensure it parses correctly
  • Use linters - Catch style and formatting issues
  • Validate in CI/CD - Automate validation in your pipeline

Validation Tools

# Command line validation
yaml-lint config.yaml

# Online validation
# Use tools like yaml.cc to validate your YAML

# Programmatic validation
import yaml
try:
    with open('config.yaml', 'r') as file:
        config = yaml.safe_load(file)
    print("YAML is valid!")
except yaml.YAMLError as e:
    print(f"YAML error: {e}")

Security Considerations

Keep security in mind when writing YAML files, especially for configuration files.

🔒 Security Best Practices

  • Never commit secrets - Use environment variables or secret management
  • Use placeholders for sensitive data - ${SECRET_KEY}
  • Validate input - Don't trust external YAML files
  • Use safe parsing - Avoid yaml.load() with untrusted input

Secure Configuration

# ✅ Good - use environment variables
database:
  host: "${DB_HOST}"
  port: "${DB_PORT}"
  username: "${DB_USERNAME}"
  password: "${DB_PASSWORD}"

api:
  secret_key: "${API_SECRET_KEY}"
  jwt_secret: "${JWT_SECRET}"

# ❌ Bad - hardcoded secrets
database:
  host: "db.example.com"
  port: 5432
  username: "admin"
  password: "super_secret_password"

api:
  secret_key: "my_secret_key_123"
  jwt_secret: "jwt_secret_456"

Practice Exercises

Apply these best practices to improve your YAML files.

Exercise 1: Refactor Configuration

Refactor this poorly structured YAML file using best practices.

Show Solution 
# Original (bad)
app:
  n: "My App"
  v: "1.0"
  env: "prod"
  db:
    h: "localhost"
    p: 5432
    u: "admin"
    pass: "secret"
  api:
    url: "https://api.example.com"
    timeout: 30

# Refactored (good)
application:
  name: "My Application"
  version: "1.0.0"
  environment: "production"

database:
  host: "localhost"
  port: 5432
  username: "${DB_USERNAME}"
  password: "${DB_PASSWORD}"

api:
  base_url: "https://api.example.com"
  timeout_seconds: 30

Exercise 2: Add Documentation

Add proper comments and documentation to this configuration file.

Show Solution 
# Application Configuration
# This file contains the main application settings
# Last updated: 2024-01-15

application:
  name: "My Application"
  version: "1.0.0"
  environment: "production"

# Database Configuration
# PostgreSQL database connection settings
database:
  host: "localhost"
  port: 5432
  username: "${DB_USERNAME}"  # Set via environment variable
  password: "${DB_PASSWORD}"  # Set via environment variable
  # Connection pool settings
  pool:
    min: 5      # Minimum connections
    max: 20     # Maximum connections
    timeout: 30 # Connection timeout in seconds

# API Configuration
# External API integration settings
api:
  base_url: "https://api.example.com"
  timeout_seconds: 30
  # Rate limiting (requests per minute)
  rate_limit: 1000
← Back: Advanced Features Next: Real-World Examples →