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 contains a list of errors to be ignored by vacuum. 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/']

Any of the matching paths will have any 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.