Spectral — Flexible JSON and OpenAPI Linter

Introduction

Spectral is an open-source JSON and YAML linter created by Stoplight. It ships with rulesets for OpenAPI v2/v3/v3.1, AsyncAPI, and Arazzo specifications, but can lint any JSON or YAML file against custom rules you define using JSONPath expressions.

What Spectral Does

• Lints OpenAPI, AsyncAPI, and Arazzo specification files against built-in best-practice rules
• Supports custom rulesets defined in YAML or JavaScript for any JSON/YAML document format
• Uses JSONPath-plus expressions to target specific parts of a document for validation
• Reports issues with severity levels (error, warning, info, hint) and exact line/column locations
• Integrates into CI pipelines, editors (VS Code extension), and API design tools

Architecture Overview

Spectral loads a ruleset (built-in or custom), parses the target document as a JSON tree, and evaluates each rule by resolving its JSONPath selector against the tree. Rules can use built-in functions (truthy, pattern, length, schema) or custom JavaScript functions for complex validation logic. Results are collected with document location info and formatted by the chosen output reporter.

Self-Hosting & Configuration

• Install the CLI: npm install -g @stoplight/spectral-cli
• Create a .spectral.yaml in your project root to extend or override the default ruleset
• Extend built-in rulesets: extends: spectral:oas or spectral:asyncapi
• Define custom rules with given (JSONPath), then (function + options), and severity
• Run in CI: spectral lint openapi.yaml --fail-severity warn

Key Features

• Built-in rulesets for OpenAPI v2, v3, v3.1, AsyncAPI v2/v3, and Arazzo v1.0
• Custom rules using JSONPath selectors and composable validation functions
• Over 20 built-in functions: truthy, falsy, pattern, enumeration, schema, length, and more
• VS Code extension for real-time linting as you edit API specs
• Multiple output formats: stylish (default), JSON, JUnit, HTML, and custom formatters

Comparison with Similar Tools

• Redocly CLI — OpenAPI linting with bundling and preview; Spectral offers more flexible custom rules via JSONPath
• openapi-generator validate — Basic validation only; Spectral provides style and best-practice enforcement beyond schema correctness
• Swagger Editor — Visual editor with inline validation; Spectral is a CLI tool for CI integration and automation
• Vacuum — High-performance OpenAPI linter in Go; Spectral has a larger rule ecosystem and JavaScript extensibility

FAQ

Q: Can I lint non-OpenAPI files with Spectral? A: Yes. Spectral can lint any JSON or YAML file. Write custom rulesets with JSONPath selectors targeting your document structure.

Q: How do I create a custom rule? A: Define a rule in .spectral.yaml with a description, given (JSONPath selector), then (validation function and options), and severity. Custom JavaScript functions can be loaded for complex logic.

Q: Does Spectral validate the OpenAPI schema itself? A: Spectral focuses on style and best-practice rules beyond basic schema validation. For strict schema correctness, combine it with a JSON Schema validator.

Q: Can I share rulesets across teams? A: Yes. Publish your ruleset as an npm package or host it at a URL. Other projects extend it with extends: ['@your-org/spectral-rules'] in their .spectral.yaml.

Sources

• https://github.com/stoplightio/spectral
• https://docs.stoplight.io/docs/spectral