Skip to content
daveshanleyPublic

About

vacuum is the worlds fastest and most versatile OpenAPI, Arazzo, AsyncAPI & JSON Schema linter, docs generator and toolkit. It tears through API specs at light speed. 100% compatible with Spectral rulesets, and OpenAPI 3.0, 3.1 and 3.2

Topics

Resources

Stars

1.1k stars

Watchers

4 watching

Forks

Latest commit

 

History

2,073 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

vacuum

The best OpenAPI, AsyncAPI, Arazzo and JSON Schema toolkit.

build discord Docs npm Docker Pulls Mentioned in Awesome Go

An ultra-super-fast, lightweight OpenAPI, AsyncAPI, Arazzo and JSON Schema linter and toolkit, originlally inspired by Spectral.


vacuum delivers world class artifacts:

  • API linting and quality analysis.
  • Supports OpenAPI, AsyncAPI, and JSON Schema as first class citizens.
  • Document bundling, and autofixing.
  • Apply OpenAPI Overlays, or build validate Arazzo workflows.
  • Agentic first, generated API documentation.
  • CI/CD Optimized with Github Actions
  • Runs with no dependencies.
  • Can operate 100% offline.

Install using the official homebrew tap

brew install --cask daveshanley/vacuum/vacuum

Install using npm

npm i -g @quobix/vacuum

Install using curl

curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

For CI/CD environments

To avoid GitHub API rate limiting in automated environments, set a GitHub token:

# Using repository token (GitHub Actions)
GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

# Using personal access token
GITHUB_TOKEN=your_github_token curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

GitHub Actions example

- name: Install vacuum
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # Increases rate limit from 60 to 5000 requests/hour
  run: |
    curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh

Note: The GitHub token prevents intermittent installation failures in CI/CD environments caused by API rate limiting. No additional permissions are required, the token only accesses public repository information.

Install using Docker

The image is available at: https://hub.docker.com/r/dshanley/vacuum

docker pull dshanley/vacuum

Multi-platform support: Docker images are available for both linux/amd64 and linux/arm64 architectures, including native ARM64 support for Apple Silicon Macs.

To run, mount the current working dir to the container and use a relative path to your spec, like so

docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>

Alternatively, you can pull it from GitHub packages. To do that, replace dshanley/vacuum with ghcr.io/daveshanley/vacuum in the above commands.

Run with Go

If you have Go 1.26 or newer installed, you can use go run to build and run it:

go run github.com/daveshanley/vacuum@latest lint <your-openapi-spec.yaml>

Upgrade vacuum

If vacuum was installed with Homebrew, npm, or the shell installer, run:

vacuum upgrade

vacuum will detect the install path and use the matching upgrade mechanism when it can. Normal commands may also show an update notice when a newer stable release is available. The passive check keeps only a small temporary cache in the OS temp directory, refreshed at most every 12 hours. Use --no-update-check or VACUUM_NO_UPDATE_CHECK=true to skip that check.


Sponsors

If your company is using vacuum, please consider supporting this project, like our very kind sponsors, past and present:

scalar

scalar

apideck

apideck


Come chat with us

Need help? Have a question? Want to share your work? Join our discord and come say hi!

Documentation

🔥 v0.40 🔥: Autofix

Found problems? Can't be bothered to fix them? vacuum can auto-fix your linting issues for you.

Native JSON and YAML reports now include diagnosticCode when available. A security requirement can also name a scheme by URI in an external document that vacuum has already loaded.


v0.40: OpenLint rulesets

Got an OpenLint ruleset? Run it with vacuum lint api.yaml --openlint -r rules.yaml.


v0.36: 12 report output formats

Export lint results in 12 formats, including SARIF, JUnit, GitLab Code Quality, HTML and Markdown. Use vacuum lint --format to choose the output, or write multiple reports from one lint run.


v0.34: Agent testing in vacuum

A new test command gives agents a way to test rules, check changes and verify repairs using vacuum's existing engine. Define a YAML or JSON suite, run vacuum test suite.yaml, and get structured results with evidence of what each rule actually did.

Check expected findings, selector matches and function calls. Test before-and-after changes, verify autofix output, and check that running a fix again makes no further change. A clean result is only useful if the rule actually ran.


v0.33: Arazzo workflow linting and a new or function

Arazzo 1.0 and 1.1 workflows are now a first-class document type in vacuum, alongside OpenAPI, AsyncAPI and JSON Schema. Use vacuum lint workflows.yaml and vacuum will detect Arazzo automatically, with recommended rules for workflow structure, references, parameters, expressions and linked source documents. Results work in the normal reports, dashboard and editor diagnostics.

The new or core function checks that at least one of two or more properties exists. Use properties: [title, summary, description] to require one of those fields. A property counts as present even when its value is null, false, 0 or an empty string.

This release also fixes AsyncAPI header, server and version checks, and improves result locations for YAML aliases and shared references.


v0.29: Lint AsyncAPI 3 documents in vacuum

AsyncAPI is now a first-class document type in vacuum, alongside OpenAPI and JSON Schema. Use the normal lint command and vacuum will detect AsyncAPI 3 documents automatically.


v0.28: Lint JSON Schema documents in vacuum

A new schema command has been added that opens up vacuum to JSON Schema specific linting rules and checks! With a whole new set of functions and rules, specifically for JSON Schema documents.

Try it out on your own JSON Schema docs! with vacuum schema


v0.27: Generate OpenAPI Documentation in vacuum

A new docs command will generate the best OpenAPI Documentation you ever saw! Now vacuum has integrated with the printing press, it means generating documentation with built-in linting results is available right inside vacuum.

Try it out! instead of the lint command try the docs command instead.


v0.25: Generate Open Collections from OpenAPI files

A new open-collection command will generate an Open Collection Workflow folder (or bundled file)

Open Collection is a new standard for defining and sharing API collections. vacuum supports it natively.

Read More


See all the documentation at https://quobix.com/vacuum


Dashboard

vacuum comes with an interactive dashboard (vacuum dashboard <your-openapi-spec.yaml>) allowing you to explore rules and violations in a console, without having to scroll through thousands of results.

dashboard

To read about the dashboard, see the dashboard command docs.

HTML Report

vacuum can generate an easy to navigate and understand HTML report. Like the dashboard you can explore broken rules and violations, but in your browser.

No external dependencies, the HTML report will run completely offline.

vacuum html-report


Build an interactive HTML report

vacuum html-report is included in official release binaries. If you install via go install github.com/daveshanley/vacuum@<version>, the command is compiled without the HTML report UI bundles. To enable it from source, run ./scripts/build-ui-assets.sh and build with -tags html_report_ui.

./vacuum html-report <your-openapi-spec.yaml | vacuum-report.json.gz> <report-name.html>

You can replace report-name.html with your own choice of filename. Open the report in your favorite browser and explore the results.

See full linting report

./vacuum lint -d <your-openapi-spec.yaml>

Lint multiple files at once

./vacuum lint -d <spec1.yaml> <spec2.yaml> <spec3.yaml>

Lint multiple files using a glob pattern

./vacuum lint -d some/path/**/*.yaml

See full linting report with inline code snippets

./vacuum lint -d -s <your-openapi-spec.yaml>

See just the linting errors

./vacuum lint -d -e <your-openapi-spec.yaml>

See just a specific category of report

./vacuum lint -d -c schemas <your-openapi-spec.yaml>

The options here are:

  • examples
  • operations
  • information
  • descriptions
  • schemas
  • security
  • tags
  • validation
  • owasp

-->READ ALL THE DOCS!<--


Tip

When using vacuum as a library You can access the fixed yaml content in the RuleSetExecutionResult.ModifiedSpec, and choose where to write the file.

When using vacuum as a cli, the --fix flag will overwrite the spec file in place, and --fix-file flag lets you specify an alternative file to write the content to, if you want to compare the outputs.

Usage

Logo gopher is modified, originally from egonelbre

About

vacuum is the worlds fastest and most versatile OpenAPI, Arazzo, AsyncAPI & JSON Schema linter, docs generator and toolkit. It tears through API specs at light speed. 100% compatible with Spectral rulesets, and OpenAPI 3.0, 3.1 and 3.2

Topics

Resources

Stars

1.1k stars

Watchers

4 watching

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages