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
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | shTo 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- 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 | shNote: 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/amd64andlinux/arm64architectures, 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.
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>
If vacuum was installed with Homebrew, npm, or the shell installer, run:
vacuum upgradevacuum 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.
If your company is using vacuum, please consider supporting this project,
like our very kind sponsors, past and present:
Need help? Have a question? Want to share your work? Join our discord and come say hi!
🔥 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.
- Get started with agent testing
- Read the
testcommand reference - Read more about execution evidence
- Use the test harness from Go
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.
- Read more about Arazzo linting in vacuum
- See the default Arazzo ruleset
- Read more about the new
orfunction
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.
- Read more about AsyncAPI linting in vacuum
- See the default AsyncAPI ruleset
- See every built-in AsyncAPI rule
- Generate an AsyncAPI ruleset
- See the AsyncAPI functions
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
- Read more about JSON Schema linting in vacuum
- Read the available
schemacommand options - See the new recommended JSON Schema ruleset
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.
- Read more about API Docs in vacuum
- Read the
docscommand reference - Read more about the printing press
- Learn about rendering modes
- Learn about diagnostics mode
- Learn about API catalogs
- Learn about agentic AI output
- Learn about generated outputs
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.
See all the documentation at https://quobix.com/vacuum
- Installing vacuum
- About vacuum
- Why should you care?
- Concepts
- FAQ
- Linting AsyncAPI
- Ignoring lint results
- Generate API Docs
- Linting JSON Schema
- Autofix!
- CLI Commands
- lint
- vacuum report
- docs
- dashboard
- html-report
- bundle - OpenAPI and AsyncAPI 3, with inline and composed output.
- spectral-report
- language-server
- upgrade
- apply-overlay
- schema
- Change Detection
- open-collection
- generate-ruleset
- version
- External References
- Exit Codes
- Developer API
- Rules
- Functions
- Understanding RuleSets
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.
To read about the dashboard, see the dashboard command docs.
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 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.
./vacuum lint -d <your-openapi-spec.yaml>
./vacuum lint -d <spec1.yaml> <spec2.yaml> <spec3.yaml>
./vacuum lint -d some/path/**/*.yaml
./vacuum lint -d -s <your-openapi-spec.yaml>
./vacuum lint -d -e <your-openapi-spec.yaml>
./vacuum lint -d -c schemas <your-openapi-spec.yaml>
The options here are:
examplesoperationsinformationdescriptionsschemassecuritytagsvalidationowasp
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.
Logo gopher is modified, originally from egonelbre
