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