Need to configure vacuum in a consistent way?

vacuum supports an optional configuration via a vacuum.conf.yaml file in the current working directory or ~/.config in your home directory (on Linux and MacOS X).

If neither of those locations are to your taste, the location of the configuration file can be set using the VACUUM environment variable.

What can be configured?

vacuum flags can be set using key value pairs in the vacuum.conf.yaml file.

For example, to set the --no-style and --hard-mode flags, you would add the following to your vacuum.conf.yaml file:

no-style: true
hard-mode: true

Here is how you can configure vacuum to always use a ruleset and a base path:

ruleset: "../rules/production-ruleset.yaml"
base: "../../specs"

Environment variable

Need to keep your configuration file in a specific location? Set the VACUUM environment variable to point to the location of your configuration file.

VACUUM="../../some/path/myconfig.yaml" vacuum lint openapi.yaml

Breaking Rules Configuration

When using change detection features, vacuum can be configured to customize which API changes are considered “breaking”. This allows you to tailor breaking change detection to match your organization’s API governance policies.

Configuration File Locations

vacuum automatically looks for a breaking rules configuration file in these locations:

  1. ./changes-rules.yaml (current working directory)
  2. ~/.config/changes-rules.yaml (user config directory)

Or specify a custom path with the --breaking-config flag:

vacuum lint new-api.yaml --original old-api.yaml --breaking-config my-rules.yaml

You can also set it via environment variable:

VACUUM_BREAKING_CONFIG="my-rules.yaml" vacuum lint new-api.yaml --original old-api.yaml

Configuration Format

The breaking rules configuration uses the same format as openapi-changes. You only need to specify rules you want to override - everything else uses sensible defaults.

Example: Allow Enum Additions

Adding new enum values is often non-breaking for many APIs. Here’s how to configure that:

# changes-rules.yaml
schemaChanges:
  enum:
    added: false    # Adding enum values is NOT breaking
    modified: true  # Modifying enum values IS breaking
    removed: true   # Removing enum values IS breaking

Example: Allow Deprecation Changes

Deprecating fields is typically non-breaking:

# changes-rules.yaml
propertyChanges:
  deprecated:
    added: false    # Adding deprecated flag is NOT breaking
    modified: false # Changing deprecated flag is NOT breaking
    removed: true   # Removing deprecated IS breaking

For the complete list of configurable rules and their default values, see the openapi-changes configuration guide.