spectral lint: Validate OpenAPI Specs in CI

spectral lint validates an OpenAPI (or AsyncAPI) document against a ruleset and exits non-zero when violations meet the fail severity.

Spectral is the de facto OpenAPI linter. In CI it keeps API specs valid and consistent, catching missing descriptions, bad refs, and style drift before clients are generated.

What it does

spectral lint parses the document, applies a ruleset (built-in spectral:oas for OpenAPI or a custom .spectral.yaml), and prints each problem with a path, severity (error/warn/info/hint), and rule name. The process exits non-zero when any result is at or above --fail-severity.

Common usage

Terminal

# run via npx without installing
npx @stoplight/spectral-cli lint openapi.yaml

# custom ruleset, JUnit output, fail only on errors
spectral lint openapi.yaml \
  --ruleset .spectral.yaml \
  -f junit -o junit.xml \
  --fail-severity=error

Flags and options

Flag	What it does
--ruleset, -r <file>	Ruleset to apply (default looks for .spectral.yaml)
--format, -f <fmt>	Output: stylish, json, junit, html, text, ...
--output, -o <file>	Write the report to a file
--fail-severity <lvl>	Minimum severity that fails the run (error/warn/...)
--display-only-failures, -D	Hide passing results
--encoding <enc>	Input encoding (default utf8)

In CI

Set --fail-severity=error so warnings inform without blocking, then tighten over time. -f junit -o junit.xml surfaces results in test-report UIs. Commit a .spectral.yaml extending spectral:oas so the rules are versioned with the spec.

Common errors in CI

"No ruleset has been defined. Please provide a ruleset ..." means there is no .spectral.yaml and you did not pass --ruleset; add one or -r spectral:oas. "Unrecognized format. The provided document does not match any of the registered formats" means the input is not valid OpenAPI/AsyncAPI (often a YAML/JSON parse error). A real lint result looks like "1:1 error oas3-schema ... must have required property "info"".