An API style guide is easier to enforce when its checkable guidelines become executable linter rules. A rule identifies where to inspect an API definition and how to validate what it finds. Run rules during design for quick feedback, then in CI/CD to catch violations before changes are merged. A passing lint check does not replace stakeholder validation or API design review. section 1.5.3 section 3.12
Before writing a custom rule:
- Look for a built-in rule that can be enabled or given a different severity; then check whether a public ruleset can be imported. section 10.1.1
- Write a failing test for behavior that still needs a custom rule. Use a core linting function if one fits; write a custom function only when the available functions cannot perform the check. section 10.1 section 10.1.1
In a Spectral ruleset, a named rule uses `given` to select document locations with JSONPath and `then` to apply a function. A useful violation `message` explains the problem; `severity` sets its level. If `given` selects nothing, the rule is not evaluated. For example, select `$.info` and apply `truthy` to its `description` field to require `info.description`. Run `spectral lint minimal.oas.yaml --ruleset simple.ruleset.yaml`; a missing description produces an error identifying the rule and the `info` location. 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
A complete YAML rule showing the selector, field check, message, and error severity for a required OpenAPI description. section 3.6
Check URI path versions
To require paths beginning with `/v{digit}/`, select path names with the JSONPath Plus expression `$.paths[*]~`, then use Spectral’s `pattern` function with `match: '^/v\d+/.*$'`. Test the selector against the definition before relying on the rule: convert the YAML file with `yq`, then run `jpp "$.paths[*]~"` against the resulting JSON to inspect the selected paths. section 3.7
For a convention such as GET `operationId` values starting with `retrieve` or `download`, the rule can target GET operation IDs and invoke a custom function. Rule configuration can be written in YAML; the custom-function example defines the rule in a TypeScript ruleset. AI coding assistants can suggest rules, but test generated rules against an OpenAPI document designed to fail. section 10.1.3 section 3.10.1
Choose error, warning, or hint levels according to the organization’s mandatory and optional guidelines. When a pipeline fails, its report should identify the affected definition location and, where useful, link to the relevant style-guide guidance. Block the pull request when the agreed failure threshold is met. Some checks—such as whether a description is meaningful—are not easy to express as ordinary Spectral rules and may still require review or another approach. section 8.11.4 section 8.11.3 section 3.11
