Spectral API Linting

Quick Start

# .spectral.yaml
extends: spectral:oas
rules:
  operation-operationId: error
  info-contact: warn
  oas3-api-servers: off

Core Concepts

• Rulesets: Collections of rules; extend built-in (spectral:oas, spectral:asyncapi)
• Severity: error, warn, info, hint, or off to disable
• Given: JSONPath expression targeting what to validate
• Then: Functions and conditions to check

Custom Rules

rules:
  must-have-description:
    description: All operations must have descriptions
    given: $.paths[*][get,post,put,patch,delete]
    severity: error
    then:
      field: description
      function: truthy

  path-must-be-kebab-case:
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-]+)+$"

Built-in Functions

• truthy / falsy - Value exists / is empty
• pattern - Regex matching
• length - String/array length constraints
• enumeration - Value in allowed list
• schema - Validate against JSON Schema
• alphabetical - Keys in order
• undefined - Property must not exist

CLI Usage

spectral lint openapi.yaml
spectral lint openapi.yaml --ruleset .spectral.yaml
spectral lint openapi.yaml -f json  # JSON output

Reference Files

• references/functions.md - All built-in functions
• references/custom-functions.md - Writing custom functions
• references/jsonpath.md - JSONPath expressions