Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
262 lines (207 sloc) 8.57 KB

Spectral Rulesets

Rulesets are a container for collections of rules. These rules are taking parameters, and calling functions on certain parts of the JSON object being linted.

CLI Usage

To get a general overview of the CLI usage, please refer to the dedicated documentation page

When you run the spectral lint my-document.json CLI command, Spectral will automatically apply the built in OpenAPI v2 or v3 ruleset if appropriate.

To customize the rules that are applied, create a spectral.yml in the same directory that you are running the spectral lint command from and it will automatically be used.

Ruleset Examples

Spectral currently support ruleset files in both yaml and json formats.

Adding a rule

Add your own rules under the rules property in your spectral.yml ruleset file.

spectral.yml

rules:
  my-rule-name:
    description: Tags must have a description.
    given: $.tags[*]
    severity: error
    then:
      field: description
      function: truthy

The example above adds a single rule that checks that tags objects have a description property defined.

Running spectral lint on the following object with the ruleset above will result in an error being reported, since the tag does not have a description:

{
  "tags": [{
    "name": "animals"
  }]
}

While running it with this object, it will succeed:

{
  "tags": [{
    "name": "animals",
    "description": "come in all shapes and sizes"
  }]
}

Adding to the recommended OpenAPI rules

Spectral comes with two built in rulesets - one for OpenAPI v2 (spectral:oas2), and one for OpenAPI v3 (spectral:oas3). Use the extends property in your ruleset file to build upon or customize other rulesets.

spectral.yml

extends: spectral:oas2
rules:
  my-rule-name:
    description: Tags must have a description.
    given: $.tags[*]
    then:
      field: description
      function: truthy

The example above will apply the recommended rules from the built in OpenAPI v2 ruleset AND apply the custom my-rule-name rule.

Enabling specific OpenAPI rules

Sometimes you might want to apply specific rules from another ruleset. Use the extends property, and pass off as the second argument in order to add the rules from another ruleset, but disable them all by default. This allows you to pick and choose which rules you would like to enable.

spectral.yml

extends: [[spectral:oas2, off]]
rules:
  # This rule is defined in the spectral:oas2 ruleset. We're passing `true` to turn it on and inherit the severity defined in the spectral:oas2 ruleset.
  operation-operationId-unique: true

The example above will run the single rulee that we enabled, since we passed off to disable all rules by default when extending the spectral:oas2 ruleset.

Disabling specific OpenAPI rules

This example shows the opposite of the Enabling specific OpenAPI rules example. Sometimes you might want to enable all rules by default, and disable a few.

spectral.yml

extends: [[spectral:oas2, all]]

rules:
  operation-operationId-unique: false

The example above will run all of the rules defined in the spectral:oas2 ruleset (rather than the default behavior that runs just the recommended ones), with one exceptions - we turned operation-operationId-unique off.

The current recommended rules are marked with the property recommended: true in their respective rulesets:

Changing the severity of a rule

spectral.yml

extends: spectral:oas2
rules:
  operation-2xx-response: warn

The example above will run the recommended rules from the spectral:oas2 ruleset, but report operation-2xx-response as a warning rather than as an error (as is the default behavior in the spectral:oas2 ruleset).

Available severity levels are error, warn, info, hint, and off.

Rules

Rules are highly configurable. There are only few required parameters but the optional ones gives powerful flexibility. Please see the following type tables for more information.

Field Type Description
given string Required Filter the target down to a subset with a JSON path. Example '$.paths..example'
then Then | Then[] Required Filter the target down to a subset with a JSON path. Example '$.paths..example'
type 'validation' | 'style'`
message string A message to be displayed when the rule validation fails
description string A short-form or long-form description of the rule formatted in plain string or markdown
severity Off = -1, Error = 0, Warning = 1, Information = 2, Hint = 3 The severity of results this rule generates
tags string[] Tags attached to the rule, which can be used for organizational purposes
recommended boolean should the rule be enabled by default?
when When A filter object to narrow down the selected items.

Then

Field Type Description
function string Required Name of the function to run. Note: to use a function you must first register it (spectral.addFunctions(...)). Please check out the default common functions.
field string Name of the field to narrow by or special @key value. If a field name is provided, the function will receive value of that field. If @key is provided, the function will receive its key.
Example: if the target object is an oas object and given = $..responses[*], then @key would be the response code (200, 400, etc) and description would be the value of each response's description
functionOptions Object Options passed to the function. Specific to the function in use.

When

Field Type Description
field string Required The path.to.prop to field, or special @key value to target keys for matched given object.

Example: if the target object is an oas object and given = $..responses[*], then @key would be the response code (200, 400, etc)
pattern string A regex pattern

Ruleset Validation

We use JSON Schema & AJV to validate your rulesets file and help you spot issues early.

Example output

$ spectral lint some-oas.yaml --ruleset acme-company.json

Reading ruleset

/rules/rule-without-given-nor-them 	 should have required property 'given'
/rules/rule-without-given-nor-them 	 should have required property 'then'
/rules/rule-with-invalid-enum/severity 	 should be number
/rules/rule-with-invalid-enum/severity 	 should be equal to one of the allowed values
/rules/rule-with-invalid-enum/type 	 should be equal to one of the allowed values

These errors should look just like errors you get from Spectral when an API description is invalid, so use them to fix your rules in the same way.

You can’t perform that action at this time.