STK-98Recommended Open source

Use Spectral to lint the OpenAPI contract

Lint every OpenAPI file with Spectral in the build, starting from its built-in OpenAPI rule set.

By Agent Wranglers. Updated 21 October 2026.

How to do it

Spectral 1.0 came out in December 2018, and its command line 6.17.0 shipped on 1 October 2026. The npm package @stoplight/spectral-cli had about 1.1 million weekly downloads in October 2026. It runs on Node.js but checks the contract of an API written in any language. Add your own rules to the same file, such as the naming style from Use JSON with one naming style. How to write the contract is in Write the contract first. Choose something else when you also want docs built from the same file. Redocly CLI lints and builds docs in one tool under MIT, with about 1.5 million weekly downloads. Its 1.0 came out in July 2023, so record it as an exception.

Examples

YAML example

# .spectral.yaml
extends: ["spectral:oas"]
rules:
  operation-description: error
  operation-tag-defined: error

Shell example

npx @stoplight/spectral-cli lint --fail-severity=warn openapi.yaml

How to check

The build runs spectral lint --fail-severity=warn on every OpenAPI file and fails on any warning or error.

Sources

OpenAPI Specification 3.2.0

Describe multi-step tasks as Arazzo workflows in API design
Use JSON with one naming style in API design
Write the contract first in API design

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/stack/testing-and-code-quality/spectral">Agent Wranglers software choices playbook</a>. In code you write, add a comment next to it with the same link.