spectral

mcclowes's avatarfrom mcclowes

Use when configuring Spectral for API linting, creating custom rulesets, and validating OpenAPI or AsyncAPI specifications

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 23, 2025
[API Helpers]

When & Why to Use This Skill

Spectral is a flexible JSON/YAML linter specifically optimized for API specifications. It enables developers to enforce design consistency, validate OpenAPI and AsyncAPI documents, and create custom governance rules to ensure high-quality API contracts across the organization.

Use Cases

  • API Design Governance: Enforce organizational standards by creating custom rulesets that mandate specific naming conventions, such as kebab-case for paths or required contact information.
  • Automated Specification Validation: Integrate into CI/CD pipelines to automatically validate OpenAPI or AsyncAPI files, catching structural errors and style violations before code generation or deployment.
  • Security and Compliance Auditing: Define rules to ensure all API endpoints have mandatory security schemes, descriptions, and proper error response schemas defined.
  • Contract Consistency: Use built-in functions like 'truthy', 'pattern', and 'alphabetical' to maintain a uniform structure across large-scale API ecosystems.
namespectral
descriptionUse when configuring Spectral for API linting, creating custom rulesets, and validating OpenAPI or AsyncAPI specifications

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