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 almost 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 JSONPath via the given keyword.

Since v0.16 vacuum only accepts RFC 9535 compliant JSONPath Query Expressions.

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.

  1. Except vacuum uses standardized JSON Path Query Expressions. ↩︎