YAML Validator

Validate and fix YAML syntax and structure for all YAML files in the project.

Purpose

Ensures YAML files follow proper syntax, have valid structure, and comply with schema requirements where applicable.

When to Use

• Creating new YAML configuration files
• Editing existing .yml/.yaml files
• Debugging YAML syntax errors
• Validating GitHub Actions workflows
• Checking docker-compose files
• Validating Kubernetes manifests
• Pre-commit YAML quality checks
• CI/CD configuration validation

YAML Syntax Rules

Basic Structure

# Comments start with #
key: value                    # Simple key-value
list:                         # Lists use dash prefix
  - item1
  - item2
nested:                       # Nested objects
  key1: value1
  key2: value2
multiline: |                  # Literal block scalar
  Line 1
  Line 2
flow: >                       # Folded block scalar
  This is a long
  sentence that folds

Data Types

string: "value"               # Quoted string
unquoted: value               # Unquoted string
number: 42                    # Integer
float: 3.14                   # Float
boolean: true                 # Boolean (true/false, yes/no, on/off)
null_value: null              # Null
empty: ~                      # Also null
multiline_string: |
  This preserves
  newlines

Indentation Rules

• Use 2 spaces per indentation level (not tabs)
• Consistent indentation throughout file
• Keys at same level must align
• Lists use 2 additional spaces after dash

# Correct
parent:
  child: value
  list:
    - item1
    - item2

# Incorrect - mixed tabs/spaces
parent:
	child: value  # Tab character!

# Incorrect - wrong indentation
parent:
 child: value   # Only 1 space

Common Issues and Fixes

Issue 1: Invalid Indentation

Problem: Mixed spaces and tabs or wrong indentation level Fix: Convert all to 2-space indentation

# Wrong
parent:
	child: value

# Correct
parent:
  child: value

Issue 2: Missing Colon

Problem: Key without colon separator Fix: Add colon and space after key

# Wrong
key value

# Correct
key: value

Issue 3: Special Characters in Strings

Problem: Characters like :, {, }, [, ] in unquoted strings Fix: Quote strings containing special characters

# Wrong
message: Error: something went wrong

# Correct
message: "Error: something went wrong"

Issue 4: Duplicate Keys

Problem: Same key defined multiple times Fix: Remove duplicate or merge values

# Wrong
config:
  key: value1
  key: value2

# Correct
config:
  key: value1
  other_key: value2

Issue 5: Unquoted Strings That Look Like Types

Problem: yes, no, on, off, true, false, numbers Fix: Quote strings that should be literal text

# Wrong - parsed as boolean true
country: YES

# Correct
country: "YES"

Issue 6: Trailing Spaces

Problem: Spaces at end of lines Fix: Remove trailing whitespace

Issue 7: Missing Document Start

Problem: File doesn’t start with --- Fix: Optional but recommended for clarity

---
# Your content here

File-Specific Validation

GitHub Actions Workflows (.github/workflows/*.yml)

Required structure:

name: Workflow Name
on: [push, pull_request]        # Event triggers
jobs:
  job-name:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Step name
        run: echo "Hello"

Common issues:

• Missing on: trigger
• Invalid runs-on value
• Missing steps:
• Old action versions (v1/v2)

Docker Compose (docker-compose.yml)

version: "3.8"
services:
  app:
    image: node:18
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production

Common issues:

• Missing version declaration
• Port binding format
• Volume mount syntax

Kubernetes Manifests (*.yaml)

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
spec:
  containers:
    - name: container-name
      image: nginx:latest

Common issues:

• Wrong apiVersion
• Missing required fields (apiVersion, kind, metadata, spec)
• List indentation under containers

Workflow

1. Parse YAML File

# Basic syntax check
python3 -c "import yaml; yaml.safe_load(open('file.yml'))"

# With better error messages
python3 -c "
import yaml
try:
    with open('file.yml') as f:
        yaml.safe_load(f)
    print('✓ Valid YAML')
except yaml.YAMLError as e:
    print(f'✗ Error: {e}')
"

2. Validate Structure

Check for:

• Valid YAML syntax
• Consistent indentation (2 spaces)
• No trailing spaces
• No tabs (spaces only)
• Proper key-value formatting
• Valid data types
• No duplicate keys

3. File-Specific Checks

Based on file location and purpose:

• GitHub Actions: Valid triggers, job structure
• Docker Compose: Version, service definitions
• K8s manifests: apiVersion, required fields
• Config files: Expected schema

4. Report Issues

For each violation:

• Line number and column
• Issue type: Error / Warning / Info
• Description of the problem
• Suggested fix with code example

Validation Commands

# Install yamllint (recommended)
pip install yamllint

# Validate single file
yamllint file.yml

# Validate with config
yamllint -c .yamllint file.yml

# Check all YAML files
find . -name "*.yml" -o -name "*.yaml" | xargs yamllint

# Using Python (if yamllint not available)
python3 -c "
import yaml
import sys
errors = []
for file in sys.argv[1:]:
    try:
        with open(file) as f:
            yaml.safe_load(f)
        print(f'✓ {file}')
    except Exception as e:
        errors.append(f'✗ {file}: {e}')
        print(f'✗ {file}: {e}')
sys.exit(1 if errors else 0)
" file1.yml file2.yml

yamllint Configuration

Create .yamllint in project root:

---
yaml-files:
  - '*.yml'
  - '*.yaml'

rules:
  braces:
    min-spaces-inside: 0
    max-spaces-inside: 0
  brackets:
    min-spaces-inside: 0
    max-spaces-inside: 0
  colons:
    max-spaces-after: 1
    max-spaces-before: 0
  commas:
    max-spaces-after: 1
    max-spaces-before: 0
  comments:
    min-spaces-from-content: 1
    require-starting-space: true
  comments-indentation: disable
  document-end: disable
  document-start: disable
  empty-lines:
    max: 2
  empty-values: disable
  indentation:
    spaces: 2
    indent-sequences: true
    check-multi-line-strings: false
  key-duplicates: enable
  key-ordering: disable
  line-length:
    max: 120
  new-line-at-end-of-file: enable
  new-lines:
    type: unix
  octal-values: disable
  quoted-strings: disable
  trailing-spaces: enable
  truthy: disable

Output Format

## YAML Validation Report

### Summary
- Files Checked: 5
- Errors: 2
- Warnings: 3
- Status: FAIL

### file1.yml
✓ Valid YAML syntax
⚠ Warning (Line 15): Line too long (145 > 120)

### file2.yml
✗ Error (Line 8, Col 5): Invalid indentation
   Current: 4 spaces
   Expected: 2 spaces
✗ Error (Line 12): Duplicate key "name"

### file3.yml
✓ Valid YAML syntax
⚠ Warning (Line 20): Trailing spaces

Best Practices

DO

✓ Use 2 spaces for indentation ✓ Quote strings with special characters (:, {, }, [, ]) ✓ Use consistent formatting throughout ✓ Validate before committing ✓ Add comments for complex sections ✓ Keep lines under 120 characters ✓ End files with newline ✓ Use --- document start marker for clarity

DON’T

✗ Use tabs for indentation ✗ Leave trailing spaces ✗ Mix quoted/unquoted styles inconsistently ✗ Use duplicate keys ✗ Forget to quote strings that look like booleans/numbers ✗ Mix YAML 1.1 and 1.2 features

Examples

Valid GitHub Actions

---
name: Rust CI
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: cargo test --all

Valid Docker Compose

---
version: "3.8"

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: production
    depends_on:
      - db

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Valid Kubernetes

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
  labels:
    app: web
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: nginx:alpine
          ports:
            - containerPort: 80

Integration

Use with:

• github-workflows: Validate workflow files
• code-quality: Pre-commit YAML checks
• debug-troubleshoot: Debug parsing errors
• feature-implement: Create new config files

Quick Fixes

# Fix trailing spaces
sed -i 's/[[:space:]]*$//' file.yml

# Convert tabs to spaces
sed -i 's/\t/  /g' file.yml

# Ensure newline at end
sed -i -e '$a\' file.yml