RuleSets are how to configure vacuum to know which rules to run for each specification, and how it should evaluate those rules.

A RuleSet is a style guide with each rule being an individual requirement as a part of the overall guide.

What does a RuleSet look like?

vacuum has based RuleSet configuration on the Spectral Ruleset model. This means Spectral RuleSets are 100% compatible with vacuum1

vacuum has added an id value to the rule (which Spectral does not), this to allow backwards compatibility, and the freedom to rename and add new names to new vacuum only content.

RuleSets contain a list of rules that should be run, and are configured using YAML or JSON, and look something like this:

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

vacuum has built-in core functions such as casing, truthy and pattern which can be used to power rules.

Rules target a section of the OpenAPI document using JSON Path via the given keyword.

The example above is a single rule that looks at all the tags object which is on the root level. The truthy function will check if the description field has been set or not.

How to apply a RuleSet?

Use the --ruleset flag with any vacuum command, supply a path to your ruleset file. For example:

vacuum html-report --ruleset <my-ruleset.yaml>

vacuum comes with two RuleSets out of the box. ‘Recommanded’ and ‘All’

Recommended is the default mode for all linting commands, recommended rules are used when the --ruleset flag is not used. Learn more about recommended rules.

‘All Rules’ is just that, all OpenAPI Rules. Everything is applied. Learn more about all rules.

Using custom messages

To use your own message when using built-in core functions, Simply provide a message property with your rule and inject what ever custom message you want to add.

For example:

 rules:
   my-vacuum-rule:
     description: Tags must have a description.
     message: Tag is missing a description! Add one please.
     given: $.tags[*]
     severity: error
     then:
       field: description
       function: truthy

The message property only works with core functions at the moment.

  1. Except custom JS functions don’t work, they’re incompatible (for now) as vacuum is written in golang not JS. vacuum will support custom functions soon. I have a few ideas about running JS code using something like otto. ↩︎