YAML Validation

Validate curl-runner YAML configuration files against the schema. Discover issues, get fix suggestions, and auto-fix common problems with a single command.

Copy Markdown

Overview

The curl-runner validate command provides comprehensive validation of your YAML configuration files. It checks structure, required fields, valid values, security issues, and common typos—with intelligent suggestions and auto-fix capabilities.

Schema Validation

Full curl-runner schema validation

Auto-Fix

15+ auto-fixable issue types

Typo Detection

Smart suggestions for misspellings

Security Checks

Detects hardcoded secrets & keys

Basic Usage

Run curl-runner validate to check your YAML files.

CLI Usage
# Validate all YAML files in current directory
curl-runner validate

# Validate specific file
curl-runner validate api.yaml

# Validate directory
curl-runner validate tests/

# Validate with glob pattern
curl-runner validate "tests/**/*.yaml"

CLI Options

-f, --fix

Automatically fix issues where possible. Fixes URL issues, method casing, header casing, and more.

-s, --strict

Treat warnings as errors. Useful for CI pipelines where you want stricter validation.

-q, --quiet

Only show files with issues. Valid files are not printed.

-h, --help

Show help message and exit.

Strict Mode
# Treat warnings as errors (for CI)
curl-runner validate --strict

# Short form
curl-runner validate -s

# Combine with quiet mode
curl-runner validate --strict --quiet

Auto-Fix

Use --fix to automatically fix common issues.

Auto-Fix Usage
# Validate and auto-fix issues
curl-runner validate --fix

# Short form
curl-runner validate -f

# Fix quietly (only show errors)
curl-runner validate -fq

# Fix specific files
curl-runner validate api.yaml --fix

Auto-Fixable Issues

  • • Lowercase HTTP methods → UPPERCASE
  • • Missing https:// prefix
  • • Protocol typos (htps, htpp, etc.)
  • • Hostname typos (locahost, etc.)
  • • Double slashes in URL paths
  • • Spaces in URLs → %20
  • • Header casing (content-type → Content-Type)
  • • Lowercase execution mode
  • • Lowercase output format
  • • Lowercase prettyLevel

Manual Fix Required

  • • Invalid auth types
  • • Missing required fields (url)
  • • Invalid status codes
  • • Schema conflicts (body + formData)
  • • Unknown keys with no suggestion
  • • Invalid port numbers
  • • Hardcoded credentials
  • • Invalid JSON body

Output Examples

The validate command provides clear, colorized output showing what passed, what failed, and the severity of each issue.

Validation Output
curl-runner validate

Files: 5 found

✓ api/users.yaml
✓ api/posts.yaml
✗ api/invalid.yaml
  ● request.url: URL should start with http:// or https://
    fix: Prepend https://
  ● request.method: Method should be uppercase: "GET"
    fix: Change to "GET"
  ▲ request.headers: Header "content-type" should be "Content-Type"
    fix: Change to "Content-Type"
  ○ request.ssl: Using insecure mode disables certificate verification
✓ api/products.yaml
✓ api/orders.yaml

Summary: 1 file(s) with 4 issue(s) (1 error, 2 warnings, 1 info)

With auto-fix enabled:

Output with --fix
curl-runner validate --fix

Files: 5 found

✓ api/users.yaml
✓ api/posts.yaml
✗ api/invalid.yaml
  ● request.url: URL should start with http:// or https://
  ● request.method: Method should be uppercase: "GET"
  ▲ request.headers: Header "content-type" should be "Content-Type"
  ○ request.ssl: Using insecure mode disables certificate verification
  ✓ Fixed 3 issue(s)
✓ api/products.yaml
✓ api/orders.yaml

Summary: 1 file(s) with 4 issue(s)
Fixed: 3 issue(s)

URL Validations

Comprehensive URL validation with typo detection and auto-fix capabilities.

URL Validations
# URL Validations

# Missing protocol (warning, auto-fixable)
request:
  url: api.example.com/users
  # Warning: URL should start with http:// or https://
  # Fix: Prepend https://

# Protocol typo (warning, auto-fixable)
request:
  url: htps://api.example.com
  # Warning: URL contains typo "htps", did you mean "https"?
  # Fix: Change "htps" to "https"

# Hostname typo (warning, auto-fixable)
request:
  url: https://locahost:3000/api
  # Warning: URL contains typo "locahost", did you mean "localhost"?
  # Fix: Change "locahost" to "localhost"

# Double slash in path (warning, auto-fixable)
request:
  url: https://api.example.com//users
  # Warning: URL contains double slash in path
  # Fix: Replace "//" with "/"

# Spaces in URL (warning, auto-fixable)
request:
  url: https://api.example.com/users /list
  # Warning: URL contains spaces
  # Fix: Encode spaces as %20

# Invalid port (error)
request:
  url: https://api.example.com:99999/api
  # Error: Invalid port number: 99999

Detected URL Typos

htpp → http
htps → https
htp → http
httpss → https
locahost → localhost
localhsot → localhost
localhos → localhost
lcoalhost → localhost

Header Validations

Validates header names, detects duplicates, and checks Content-Type consistency.

Header Validations
# Header Validations

# Wrong casing (warning, auto-fixable)
request:
  url: https://api.example.com
  headers:
    content-type: application/json
    authorization: Bearer token
  # Warning: Header "content-type" should be "Content-Type"
  # Warning: Header "authorization" should be "Authorization"

# Content-Type mismatch (info)
request:
  url: https://api.example.com
  method: POST
  headers:
    Content-Type: application/json
  formData:
    field: value
  # Info: Using formData but Content-Type is not multipart/form-data

# Duplicate headers (warning)
request:
  url: https://api.example.com
  headers:
    Content-Type: application/json
    content-type: text/plain
  # Warning: Duplicate header detected (case-insensitive)

Standard Header Casing

Content-Type
Authorization
Accept
Cache-Control
Content-Length
User-Agent
X-Requested-With
X-API-Key
Accept-Encoding

Security Validations

Detects potential security issues like hardcoded credentials and API keys.

Security Validations
# Security Validations

# Hardcoded credentials (warning)
request:
  url: https://api.example.com
  auth:
    type: basic
    username: admin
    password: secret123
  # Warning: Possible hardcoded password detected
  # Suggestion: Use environment variables

# JWT in header (warning)
request:
  url: https://api.example.com
  headers:
    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.signature
  # Warning: Possible hardcoded JWT token
  # Suggestion: Use ${env.TOKEN} instead

# API key patterns (warning)
request:
  url: https://api.example.com
  headers:
    X-API-Key: sk-live-xxxxxxxxxxxxx
  # Warning: Possible hardcoded API key
  # Suggestion: Use environment variables

# Insecure mode (info)
request:
  url: https://api.example.com
  ssl:
    insecure: true
  # Info: Using insecure mode disables certificate verification

Detected Patterns

  • • JWT tokens (Bearer eyJ...)
  • • Stripe API keys (sk_live_*, sk_test_*)
  • • AWS access keys (AKIA...)
  • • Common password field names (password, passwd, secret, api_key, etc.)
  • • Hardcoded bearer tokens
  • • Insecure SSL mode

Unknown Key Detection

Detects unknown configuration keys and suggests corrections using edit distance matching.

Unknown Key Detection
# Unknown Key Detection with Suggestions

# Typo in key name
request:
  url: https://api.example.com
  methood: GET
  # Error: Unknown key "methood". Did you mean "method"?

# Typo in nested key
request:
  url: https://api.example.com
  auth:
    tpye: bearer
    token: ${TOKEN}
  # Error: Unknown key "tpye" in auth. Did you mean "type"?

# Global config typo
global:
  excution: parallel
  # Error: Unknown key "excution". Did you mean "execution"?

What Gets Validated

The validator checks all aspects of your curl-runner configuration.

Structure

  • • Must have request, requests, or collection
  • • Unknown keys are flagged with suggestions
  • • Valid YAML syntax
  • • Duplicate request names detected

Request Fields

  • • url - Required, validated format
  • • method - GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
  • • headers - Casing, duplicates
  • • body - JSON validation, method compatibility

Authentication

  • • auth.type - basic or bearer
  • • basic auth requires username
  • • bearer auth requires token
  • • Hardcoded credential detection

SSL/TLS Config

  • • cert without key is flagged
  • • key without cert is flagged
  • • Path values must be strings
  • • Insecure mode warning

Expect Assertions

  • • Status codes must be 100-599
  • • Response time format validation
  • • Headers must be an object
  • • Duration format (e.g., <500ms)

Global Config

  • • execution: sequential or parallel
  • • output.format: json, pretty, raw
  • • output.prettyLevel: minimal, standard, detailed
  • • ci.failOnPercentage: 0-100

Timeouts & Retries

  • • timeout must be positive number
  • • retry.count must be non-negative
  • • retry.delay must be non-negative
  • • retry.maxDelay must be non-negative

Proxy Config

  • • proxy.url must be valid URL
  • • proxy.auth requires username
  • • Proxy URL protocol validation

Valid Configuration Examples

Here are examples of properly configured YAML files that pass validation.

Valid Request
# Valid request configuration
request:
  name: Get User
  url: https://api.example.com/users/1
  method: GET
  headers:
    Authorization: Bearer ${TOKEN}
    Content-Type: application/json
  timeout: 5000
  expect:
    status: 200
    headers:
      content-type: application/json
    body:
      id: 1

Global configuration:

Valid Global Config
# Valid global configuration
global:
  execution: parallel
  maxConcurrency: 5
  continueOnError: true
  output:
    format: pretty
    prettyLevel: detailed
  ci:
    strictExit: true
    failOn: 2
    failOnPercentage: 10

requests:
  - url: https://api.example.com/users
  - url: https://api.example.com/posts

Common Validation Errors

Here are examples of common validation errors and how to fix them.

Common Errors
# Common validation errors

# Missing URL (error)
request:
  method: GET
  # Error: URL is required

# Invalid method (error)
request:
  url: https://api.example.com
  method: INVALID
  # Error: Invalid method "INVALID". Must be: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

# Lowercase method (warning, auto-fixable)
request:
  url: https://api.example.com
  method: get
  # Warning: Method should be uppercase: "GET"

# Invalid auth type (error)
request:
  url: https://api.example.com
  auth:
    type: oauth
  # Error: Invalid auth type "oauth". Must be: basic, bearer

# Invalid status code (error)
request:
  url: https://api.example.com
  expect:
    status: 1000
  # Error: Status code must be a number between 100-599

# Body and formData conflict (error)
request:
  url: https://api.example.com
  body: { "test": "value" }
  formData:
    field: value
  # Error: Cannot use both "body" and "formData"

# Body with GET (warning)
request:
  url: https://api.example.com
  method: GET
  body: { "test": "value" }
  # Warning: GET requests should not have a body

# Duplicate request names (warning)
requests:
  - name: GetUser
    url: https://api.example.com/users/1
  - name: GetUser
    url: https://api.example.com/users/2
  # Warning: Duplicate request name "GetUser"

CI/CD Integration

Use validation in your CI/CD pipeline to catch configuration errors before deployment.

CI Integration
# GitHub Actions
- name: Validate YAML configs
  run: curl-runner validate tests/ --quiet

# GitLab CI (strict mode fails on warnings)
validate:
  script:
    - curl-runner validate tests/ --strict

# Pre-commit hook
curl-runner validate && curl-runner tests/

Exit Codes

  • • 0 - All files valid (no errors)
  • • 1 - One or more files have errors
  • • 1 (with --strict) - Files have errors OR warnings

Best Practices

Recommended

• Run validation before committing changes
• Use --strict in CI pipelines
• Use --quiet in automated scripts
• Review auto-fixes before committing
• Use environment variables for credentials
• Validate entire test directories at once

Considerations

• Auto-fix changes files in place
• Some issues require manual intervention
• Warnings don't fail validation (unless --strict)
• Variables (${{VAR}) are not resolved during validation
• Security warnings suggest using env vars

Severity Levels

Error●

Must be fixed. Fails validation.

Warning▲

Should be fixed. Often auto-fixable. Fails with --strict.

Info○

For awareness. Does not affect exit code.