Ignoring Violations

Ignoring errors is useful for when you want to implement new rules to existing production APIs.

In some cases, correcting the lint errors would result in a breaking change.

Having a way to ignore these errors allows you to implement new rules for new APIs while maintaining backwards compatibility for existing ones.

Ignoring specific linting errors

You can ignore specific linting errors by providing an --ignore-file argument to the lint and report commands.

The ignore-file should point to a .yaml file that maps a rule id to one or more ignore selectors.

Each selector can be either:

• an exact result path generated by vacuum generate-ignorefile or doctor
• a JSONPath expression that matches one or more nodes in the source OpenAPI document

The structure of the yaml file is as follows:

rule-id-1:
  - <json_path_to_error_or_warning_1>
  - <json_path_to_error_or_warning_2>
rule-id-2:
  - <json_path_to_error_or_warning_1>
  - <json_path_to_error_or_warning_2>
  ...

Example ignore file

component-description:
  - $.paths['/burgers']
  - $.paths['/burgers/{burgerId}']
  - $.paths['/burgers/{burgerId}/dressings']
  - $.paths['/dressings/{dressingId}']
  - $.paths['/dressings']
paths-kebab-case:
  - $.paths['/burgers/notKebabCase/']
  - $.paths['/NotKebabCase/notKebabCase/']

Exact paths remain fully supported and are checked first, so existing ignore files continue to work as-is.

Example ignore file using JSONPath expressions

operation-description:
  - $.paths[*].get
  - $.paths[*].post
tag-description:
  - $.tags[*]

These selectors are resolved against the source specification before results are filtered, so a single wildcard expression can ignore multiple matching violations.

Any matching exact path or expression result will have the corresponding results stripped out of the final report.

This ignore file feature was a community contribution by Calvin Lobo.

Hard ignore extension

Need to make parts of the spec vanish completely? Ignore rules not enough?

Then you can use the x-lint-ignore extension.

  schema:
    type: [object]
    x-lint-ignore: [oas3-missing-example, description-duplication]
    ...

Just add x-lint-ignore: rule-id to the yaml or JSON node reporting the failure (or x-lint-ignore: [rule-one, rule-two] if there are multiple issues to ignore.

vacuum will drop all results that contain that extension.

This allows folks migrating from zally to keep existing x-zally-ignore issues silenced.

The x-lint-ignore capability was a community contribution from Tristan

To try and create something other linters can use, I kept away from using vacuum in the extension name.