A ruleset groups executable checks for an API definition. It turns applicable API style-guide conventions into repeatable linting feedback: a linter reports where the definition fails a rule. Run those checks while designing the API, then rerun them when the definition changes. Automated compliance does not replace stakeholder review or checks that need a separate tool, such as comparing definitions for breaking changes. section 1.5.3 section 3.12
In Spectral, a YAML ruleset can define rules under `rules`. A rule’s `given` JSONPath selects where to check; `then` names the check, while `message` and `severity` determine what a violation reports. If `given` selects nothing, that rule is not evaluated. A ruleset can also be JSON or JavaScript. section 3.6
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
The rule selects `$.info` and uses `truthy` to require its `description` field. Run `spectral lint minimal.oas.yaml --ruleset simple.ruleset.yaml` against a definition without that field; the reported problem is an error. section 3.6
Configure a ruleset for the project rather than rewriting every useful check:
- Import reusable rules with `extends`, such as `extends: ["spectral:oas"]`. Sources can include built-in, local, HTTP-hosted and NPM rulesets; an imported rule can be switched off or assigned another severity. section 3.8
- Check built-in and open-source rules before maintaining a custom rule or function. Extending `spectral:oas` enables its recommended rules; enabling all its rules requires an explicit option. section 10.1.1
- For an existing API, use `overrides` to turn a failing rule off or reduce its severity for a specified file or OpenAPI object. Keep the rule active elsewhere so new work can meet the current standard. section 3.9
Read the result before changing the policy
A minimal OpenAPI definition checked against `spectral:oas` produces three warnings and no errors; it remains valid despite missing recommended details. Switching off the imported `info-description` rule removes that warning, leaving two problems. By contrast, turning an `operationId` rule off for an entire existing file hides all its errors there; a narrower override can suppress one operation and leave another as a warning. Choose the scope deliberately. section 3.8 section 3.9
For immediate feedback, set the VS Code Spectral extension’s `Spectral:Ruleset` setting to the ruleset file. Violations then appear on affected lines, with details on hover and in the Problems tab. Spectral can also run from the command line, making the same kind of compliance check available in a CI/CD pipeline. section 3.5 section 1.5.3
