spectral

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

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill empowers developers to automate API governance and quality assurance using Spectral. It facilitates the creation of custom rulesets and the rigorous validation of OpenAPI and AsyncAPI specifications, ensuring that API designs are consistent, secure, and compliant with industry standards before implementation.

Use Cases

  • Automated API Linting: Instantly validate OpenAPI or AsyncAPI definitions against standard rulesets to catch design errors and documentation gaps early in the development cycle.
  • Custom Style Guide Enforcement: Create and apply organization-specific rulesets to ensure all microservices follow consistent naming conventions, security headers, and response structures.
  • Ruleset Development & Debugging: Assist in writing complex JSONPath expressions and custom functions for Spectral to target specific parts of an API specification for validation.
  • CI/CD Pipeline Integration: Provide guidance on configuring Spectral CLI within automated workflows to prevent non-compliant API contracts from being merged or deployed.
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