An API linting rule needs to find the right part of a definition before it can check anything. JSONPath is a query language that selects data from a JSON document. An expression starts with `$`, the document root, then navigates through child elements using dots or brackets. For example, `$.info.version` selects the version value from an OpenAPI definition’s `info` object. section 3.6
In a Spectral rule, `given` holds the JSONPath expression that selects where the rule applies; `then` specifies the check. The expression can select zero or more elements. If it selects none, the rule is not evaluated—an important distinction when deciding whether a missing element should itself be reported. 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
This rule selects `$.info`, then checks its `description` field with Spectral’s `truthy` function. Selecting the containing object lets the rule report a missing description. section 3.6
Some checks need more than basic JSONPath. To check whether every URI path starts with a version number, Spectral uses the JSONPath Plus expression `$.paths[*]~` to select the path names. The rule’s `pattern` function then checks those names against `^/v\d+/.*$`. To inspect the selection before linting, convert the OpenAPI YAML file with `yq eval -o=json product-catalog-v3.oas.yaml > product-catalog-v3.oas.json`, then run `jpp "$.paths[*]~" product-catalog-v3.oas.json`; `jpp` prints the matching paths. section 3.7
Targeting GET operation IDs
A custom Spectral rule can use `$.paths[*].get.operationId` as its `given` expression. This selects GET operation IDs for a custom function that checks their naming convention, rather than applying the function to every field in the definition. section 10.1.3
