An API style guide is useful only if teams can check definitions against it consistently. Spectral is an open-source linter that compares a JSON or YAML API definition with a ruleset and reports violations. It can run from a command line, an editor, or a pull-request pipeline. Linting automates specified checks; it does not replace API design review. section 3.12 section 3.3
Check a definition against a ruleset
Run `spectral lint product-catalog.oas.yaml --ruleset json-api.ruleset.yaml --verbose`. A result saying `No results with a severity of 'error' found!` means no error-level violation was reported; it does not rule out warnings. A violation report identifies a line and column, severity, rule name, message, and location in the definition. For example, a `response-content-type` error at `41:30` points to an `application/json` response where the JSON:API ruleset requires `application/vnd.api+json`. section 3.4
To see violations while editing, install and enable the Spectral extension in VS Code, then set `Spectral:Ruleset` to the ruleset file. Problem lines are highlighted; hovering or opening the Problems tab shows the message. section 3.5
Listing 3.1 A Spectral rule to check that info.description is present
rules:
info-description-is-required: #1
message: "API definition files must
have info.description defined" #2
severity: error #3
given: $.info #4
then:
field: description #5
function: truthy #6
This YAML rule checks for `info.description`. `given: $.info` selects the object; `then` applies the `truthy` function to its `description` field. The rule’s message and severity shape the reported error. If `given` selects nothing, the rule is not evaluated. section 3.6
Rules can check more than field presence. To require versioned URI paths, select path names with the JSONPath Plus expression `$.paths[*]~`, then use Spectral’s `pattern` function with `^/v\d+/.*$`. Test a selector against the definition before relying on the rule. section 3.7
Reuse rules through `extends`: a ruleset can import `spectral:oas`, local or remote rulesets, or NPM-hosted rulesets. An imported rule’s severity can be changed or set to `off`. Without an explicit `--ruleset`, Spectral looks for `.spectral.yaml`, `.spectral.yml`, or `.spectral.json` in the current directory. section 3.8
For an existing API that cannot meet every new rule immediately, use `overrides` to adjust a named rule for a file or a specific OpenAPI object. An override reference combines a file-path glob with a JSON pointer; the operation example uses a percent-encoded pointer. Review disabled rules later rather than treating exceptions as proof of consistency. section 3.9
To make linting a pull-request check, add a pipeline step that runs `npx @stoplight/spectral-cli lint` with the API definition and `--ruleset` paths. This runs the CLI on the runner without a separate Spectral installation; a Spectral GitHub action is another option. section 8.5.3
