---
title: "Use Spectral to lint the OpenAPI contract · Agent Wranglers"
url: https://agentwranglers.se/playbook/stack/testing-and-code-quality/spectral
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Use Spectral to lint the OpenAPI contract

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Testing and code quality](https://agentwranglers.se/playbook/stack/testing-and-code-quality.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

- ID: STK-98
- Level: Recommended
- Chapter: [Testing and code quality](https://agentwranglers.se/playbook/stack/testing-and-code-quality)
- Rule: Lint every OpenAPI file with Spectral in the build, starting from its built-in OpenAPI rule set.
- Cost: Open source. Apache-2.0 licence, free to run in any build.
- How: 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](https://agentwranglers.se/playbook/api-design/requests-and-responses/json-conventions). How to write the contract is in [Write the contract first](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-contract). 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.
- Check: The build runs `spectral lint --fail-severity=warn` on every OpenAPI file and fails on any warning or error.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

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

### Shell example

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

## Sources

- [OpenAPI Specification 3.2.0](https://spec.openapis.org/oas/v3.2.0.html)

## Related rules

- [Describe multi-step tasks as Arazzo workflows](https://agentwranglers.se/playbook/api-design/contracts-and-docs/arazzo-workflows) in API design
- [Use JSON with one naming style](https://agentwranglers.se/playbook/api-design/requests-and-responses/json-conventions) in API design
- [Write the contract first](https://agentwranglers.se/playbook/api-design/contracts-and-docs/openapi-contract) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Use Locust for load tests](https://agentwranglers.se/playbook/stack/testing-and-code-quality/locust)
- [Testing and code quality](https://agentwranglers.se/playbook/stack/testing-and-code-quality)