JSONPath is an expression syntax for selecting values inside JSON or YAML documents. In API linting, it identifies the OpenAPI elements that a rule should check before a function evaluates them. section 18.3.2 section 18.5
Use JSONPath operators to move from broad document locations to precise targets:
- $ selects the document root, while a.b selects b inside a. section 18.10
- Use a.* for object values or array items, ..b to find b throughout the document, and [a,b] to select either named key. section 18.5.2
- Use a[?(condition)] to filter matching elements; @ denotes the current element, and expressions can use equality and logical operators. section 18.5.2
Selecting API elements
The path $..parameters[?(@.in === "query" || @.in === "path")] finds query and path parameters wherever they are defined. The path $.paths.*[post,put].responses finds responses for POST and PUT operations. Prefer several clear paths when one complex path could produce unexpected matches. section 18.5.2
Testing a path before checking values
When developing a Spectral rule, temporarily pair the target path with the undefined function. Running it against a realistic, valid OpenAPI document reveals exactly which locations the JSONPath selects; replace the temporary check afterward. section 18.5.1
Figure 18.8 Use a.*,..b, and [?(conditions)] to get all query and path parameters with JSONPath.
The figure visualizes how wildcards, recursive descent, and conditional filters locate query and path parameters across an OpenAPI document. section 18.5.2
