yaml-validator

Original：🇺🇸 English
Translated

Validates YAML syntax and structure for all .yml and .yaml files in the project. Identifies common issues like invalid syntax, indentation errors, missing keys, type mismatches, and provides fixes. Use when editing, creating, or debugging YAML configuration files.

1installs
Sourced-o-hub/rust-self-learning-memory
Added on

NPX Install

npx skill4agent add d-o-hub/rust-self-learning-memory yaml-validator

Tags

Translated version includes tags in frontmatter
yaml-validationconfiguration-checkyamllintci-cd-integrationsyntax-fix

SKILL.md Content

View Translation Comparison →

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

yaml
# 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

yaml
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
yaml
# 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
yaml
# Wrong
parent:
	child: value

# Correct
parent:
  child: value

Issue 2: Missing Colon

Problem: Key without colon separator Fix: Add colon and space after key
yaml
# Wrong
key value

# Correct
key: value

Issue 3: Special Characters in Strings

Problem: Characters like 
:
, 
{
, 
}
, 
[
, 
]
in unquoted strings Fix: Quote strings containing special characters
yaml
# 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
yaml
# 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
yaml
# 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
yaml
---
# Your content here

File-Specific Validation

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

Required structure:
yaml
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
)

yaml
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
)

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

bash
# 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

bash
# 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
---
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

yaml
---
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

yaml
---
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

yaml
---
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

bash
# 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