Spectral

Visit Website

Introduction

Spectral is a flexible linter for JSON and YAML documents, best known for checking API descriptions. It ships ready-to-use rulesets that validate and lint OpenAPI v2, v3.0, v3.1 and v3.2, AsyncAPI and Arazzo v1 documents, and lets teams write their own rules to build automated API style guides.

A ruleset is a YAML, JSON or JavaScript file that extends built-in rulesets and adds rules. Each rule selects parts of a document with JSONPath and applies a function to them, such as pattern, truthy, length, alphabetical, enumeration or schema. Built-in functions cover most checks, and custom JavaScript functions handle the rest. Severity levels (error, warn, info, hint) decide what fails a build.

Typical rules check that every operation has an operationId and description, that paths use kebab-case, that error responses follow a standard shape, that examples match schemas, or that security schemes are defined. Shared rulesets let an organisation publish one style guide and reuse it across hundreds of APIs.

Spectral runs as a CLI (spectral lint), as a JavaScript library, and inside editors through Stoplight’s VS Code extension. It outputs results in several formats, including human-readable text, JSON, JUnit and HTML, so it fits pre-commit hooks and CI pipelines. Stoplight, the company behind it, is part of SmartBear.

The project has about 3,300 GitHub stars and released v6.17.1 on 6 November 2026.

In the quality loop, Spectral checks API contracts at design time and in CI, before any code runs. It complements contract-testing and breaking-change tools such as oasdiff, Specmatic or Pact: Spectral checks that a description is well-formed and consistent, while those tools check compatibility and behaviour.

The source code is at stoplightio/spectral on GitHub under the Apache-2.0 licence, with about 3,300 stars; the most recent commit was on 6 November 2026.

A good rollout keeps Spectral helpful rather than noisy. Begin with the built-in OpenAPI ruleset in warning mode, fix the issues that matter most, and then promote selected rules to errors so they block merges. Custom rules are where Spectral earns its place: naming conventions, required error formats, pagination patterns and security schemes can all be encoded once and applied to every API description in the organisation. Keep the ruleset in its own repository and version it, so teams can upgrade deliberately. Spectral lints the description, not the running API, so pair it with contract or API tests that check the implementation matches.

Features

1. Built-in rulesets: OpenAPI 2.0 to 3.2, AsyncAPI and Arazzo.
2. Custom rules: JSONPath selectors plus built-in or custom functions.
3. Rule severities: Error, warning, info and hint levels.
4. Shared style guides: Extend and publish rulesets across teams.
5. Custom functions: Write JavaScript for complex checks.
6. CLI and library: Use in terminals, scripts and Node.js.
7. Editor integration: Live linting in VS Code via Stoplight’s extension.
8. Multiple formats: Text, JSON, JUnit and HTML output, among others.
9. Any JSON/YAML: Lint configuration files, not only APIs.
10. Overrides: Disable or adjust rules for specific files or paths.

Pros

1. Catches issues early: Problems are found before implementation or review.
2. Widely adopted: A de facto standard for OpenAPI linting.
3. Free to use: Open source under the Apache-2.0 licence, so the core tool costs nothing to use.
4. Actively maintained: The repository had commits as recent as 6 November 2026.
5. Community: About 3,300 GitHub stars.

Cons

1. Rule writing takes effort: Good style guides need time to design and tune.
2. Static checks only: Does not test a running API.
3. Noise risk: Overly strict rulesets can overwhelm teams with warnings.

Usage and Links (Example)

Install and lint an OpenAPI file with the built-in ruleset:

npm install -g @stoplight/spectral-cli
echo 'extends: ["spectral:oas"]' > .spectral.yaml
spectral lint openapi.yaml

Add a custom rule:

extends: ["spectral:oas"]
rules:
  paths-kebab-case:
    description: Paths must be kebab-case.
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-{}]+)+$"

Practical tips:

1. Start with the built-in ruleset, then add a few high-value custom rules.
2. Fail CI only on errors at first; treat warnings as advice.
3. Publish your ruleset as a package so every API repository uses the same version.

Resources:

• Spectral website
• GitHub repository

Pricing

Spectral is free and open source under the Apache-2.0 licence.

Recommended for?

1. API platform teams enforcing style guides across many APIs.
2. Design-first teams working with OpenAPI or AsyncAPI.
3. Not a fit as a replacement for runtime API tests.

Conclusion

Spectral is the standard open-source linter for API descriptions. It is flexible enough for organisation-wide style guides and simple enough to start with in minutes.

Combined with a breaking-change checker and runtime tests, it gives API teams strong guardrails early in the loop.

On CheckOps, Spectral is filed under the API & contract testing and Release & CI gates stages. Related tools listed here include oasdiff, Stoplight Prism, Specmatic, Schemathesis, SwaggerUI and Dredd. Before choosing, compare them on licence, supported languages and platforms, hosting model, and how well each fits your existing CI pipeline. Facts on this page were checked against the official website, documentation and repository on 11 November 2026; statements the vendor makes about its own product are marked as vendor claims.