vacuum
An ultra-super-fast, lightweight OpenAPI linter and quality checking tool
About vacuum
This large README is shown as a plain-text preview. Read the full README at the source
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/logo-dark.png">
<img alt="vacuum" src=".github/assets/logo-light.png">
</picture>
# The world's fastest OpenAPI, AsyncAPI, Arazzo and JSON Schema linter.
[](https://discord.gg/UAcUF78MQN)
[](https://pkg.go.dev/github.com/daveshanley/vacuum)
[](https://www.npmjs.com/package/@quobix/vacuum)
[](https://hub.docker.com/r/dshanley/vacuum)
[](https://github.com/avelino/awesome-go)
An **ultra-super-fast**, lightweight OpenAPI, AsyncAPI, Arazzo and JSON Schema linter and quality checking tool inspired by [Spectral](https://github.com/stoplightio/spectral).
It supports Spectral-style YAML and JSON rulesets. See [Spectral migration](#spectral-migration) for compatibility limits and built-in alternatives.
## Install using the official [homebrew](https://brew.sh) tap
```
brew install --cask daveshanley/vacuum/vacuum
```
## Install using [npm](https://npmjs.com)
```
npm i -g @quobix/vacuum
```
## Install using [yarn](https://yarnpkg.com/)
```
yarn global add @quobix/vacuum
```
## Install using curl
```bash
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:
```bash
# 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
```yaml
- 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](https://hub.docker.com/r/dshanley/vacuum)
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](https://github.com/daveshanley/vacuum/pkgs/container/vacuum).
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:
```bash
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](https://github.com/sponsors/daveshanley),
like our _very kind_ sponsors, past and present:
<a href="https://scalar.com">
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/scalar-dark.png">
<img alt="scalar" src=".github/sponsors/scalar-light.png">
</picture>
</a>
[scalar](https://scalar.com)
<a href="https://apideck.com">
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/apideck-light.png">
<img alt="apideck" src=".github/sponsors/apideck-dark.png">
</picture>
</a>
[apideck](https://apideck.com)
---
## Come chat with us
Need help? Have a question? Want to share your work? [Join our discord](https://discord.gg/UAcUF78MQN) and
come say hi!
## Documentation
š„ **New in** `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](https://quobix.com/vacuum/arazzo/)
- [See the default Arazzo ruleset](https://quobix.com/vacuum/rulesets/arazzo-recommended/)
- [Read more about the new `or` function](https://quobix.com/vacuum/functions/core/or/)
---
`v0.29`: **Lint AsyncAPI 3 documents in vacuum**
[AsyncAPI](https://www.asyncapi.com) 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](https://quobix.com/vacuum/asyncapi/)
- [See the default AsyncAPI ruleset](https://quobix.com/vacuum/rulesets/asyncapi-recommended/)
- [See every built-in AsyncAPI rule](https://quobix.com/vacuum/rulesets/asyncapi/)
- [Generate an AsyncAPI ruleset](https://quobix.com/vacuum/commands/generate-ruleset/)
- [See the AsyncAPI functions](https://quobix.com/vacuum/functions/asyncapi/)
---
`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](https://quobix.com/vacuum/json-schema/)
- [Read the available `schema` command options](https://quobix.com/vacuum/commands/schema/)
- [See the new recommended JSON Schema ruleset](https://quobix.com/vacuum/rulesets/json-schema-recommended/)
---
`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](https://github.com/pb33f/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](https://quobix.com/vacuum/api-docs/)
- [Read the `docs` command reference](https://quobix.com/vacuum/commands/docs/)
- [Read more about the printing press](https://pb33f.io/printing-press/)
- [Learn about rendering modes](https://pb33f.io/printing-press/rendering-modes/)
- [Learn about diagnostics mode](https://pb33f.io/printing-press/diagnostics-mode/)
- [Learn about API catalogs](https://pb33f.io/printing-press/api-catalog/)
- [Learn about agentic AI output](https://pb33f.io/printing-press/agentic-ai/)
- [Learn about generated outputs](https://pb33f.io/printing-press/outputs/)
---
`v0.25`: **Generate Open Collections from OpenAPI files**
A new `open-collection` command will generate an [Open Collection](https://www.opencollection.com/) Workflow folder
(or bundled file)
Open Collection is a new standard for defining and sharing API collections. vacuum supports it natively.
[Read More](https://quobix.com/vacuum/commands/open-collection/)
---
`v0.24`: **TURBO MODE**
A huge tune up of hundreds of systems across the stack has resulted in significant speed boosts and improved memory performance.
| Spec | Size | v0.23 | Turbo | Speedup |
|------|------|-------|-------|-----|
| petstore.yaml | 21KB | 0.03s | 0.02s | 33% |
| mistral.yaml | 292KB | 0.17s | 0.10s | 41% |
| neon.yaml | 370KB | 0.21s | 0.08s | 62% |
| ld.yaml | 1.9MB | 0.93s | 0.31s | 67% |
| plaid.yml | 2.9MB | 1.39s | 0.53s | 62% |
| stripe.yaml | 6.1MB | 3.11s | 0.85s | 73% |
The bigger the spec, the faster vacuum runs!
New `-T` flag will enable **turbo mode**. Go ultra-fast!
---
`v0.23`: **OpenAPI Overlay Support**
Ever needed to tweak an OpenAPI spec for different environments without maintaining multiple copies?
Maybe swap out server URLs between dev, staging, and production? Or perhaps strip out internal endpoints before publishing the API docs?
OpenAPI Overlays are the answer. They let us make non-destructive modifications to specs using JSONPath expressions to
target exactly what we want to change. vacuum now supports a new `apply-overlay` command.
- [Learn more about the apply-overlay command](https://quobix.com/vacuum/commands/apply-overlay)
`apply-overlay` can also build a fail-closed publication document after applying
the standard Overlay actions:
```bash
vacuum apply-overlay internal.yaml public.overlay.yaml public.yaml \
--include-tag public \
--tag-match any \
--prune-unused
```
Inclusive tags are exact and case-sensitive; `any` keeps operations with at
least one included tag and `all` requires every included tag. Untagged
operations are removed. Filtering runs after Overlay actions and before
reachability-based component pruning. These opt-in transforms require a
bundled, self-contained OpenAPI document. Top-level Tag Objects are retained.
YAML aliases and merge keys are expanded when filtering. Retained mapping
order, comments, and scalar styles are preserved. Pruning rejects schema
`$id` scopes that cannot be resolved safely. Link Objects targeting filtered
operations are retained and reported as warnings. Document output remains
pure on stdout; warnings are written to stderr. The warning summary uses the `apply-overlay produced` prefix to
cover both Overlay actions and publication transforms.
---
`v0.22`: **Async Functions / Promises, Fetch & Batch mode in Custom JS Functions**
Do you want to call remote APIs in your vacuum javascript functions? What about async processing or the ability to use Promises?
vacuum now has its own event loop and will happily support `async` and `await`. Combined with a full implementation of [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
Also added **Batch Mode**. This allows custom functions to receive the entire list of nodes, instead of firing the function
for each result, so you can send all your data off to an API or an LLM, and have the ability parse and process everything at once
vs individually.
- [Read all about async JS functions in vacuum](https://quobix.com/vacuum/api/custom-javascript-functions/#async-functions--promises)
- [Learn about using fetch in vacuum](https://quobix.com/vacuum/api/custom-javascript-functions/#fetch-api)
- [find out how batch mode works](https://quobix.com/vacuum/api/custom-javascript-functions/#batch-mode-processing)
---
### [Quick Start Guide š](https://quobix.com/vacuum/start)
See all the documentation at https://quobix.com/vacuum
- [Installing vacuum](https://quobix.com/vacuum/installing/)
- [About vacuum](https://quobix.com/vacuum/about/)
- [Why should you care?](https://quobix.com/vacuum/why/)
- [Concepts](https://quobix.com/vacuum/concepts/)
- [FAQ](https://quobix.com/vacuum/faq/)
- [Linting AsyncAPI](https://quobix.com/vacuum/asyncapi/)
- [Ignoring lint results](https://quobix.com/vacuum/ignoring/)
- [Generate API Docs](https://quobix.com/vacuum/api-docs/)
- [Linting JSON Schema](https://quobix.com/vacuum/json-schema/)
- [CLI Commands](https://quobix.com/vacuum/commands/)
- [lint](https://quobix.com/vacuum/commands/lint/)
- [vacuum report](https://quobix.com/vacuum/commands/report/)
- [docs](https://quobix.com/vacuum/commands/docs/)
- [dashboard](https://quobix.com/vacuum/commands/dashboard/)
- [html-report](https://quobix.com/vacuum/commands/html-report/)
- [bundle](https://quobix.com/vacuum/commands/bundle/)
- [spectral-report](https://quobix.com/vacuum/commands/spectral-report/)
- [language-server](https://quobix.com/vacuum/commands/language-server/)
- [upgrade](https://quobix.com/vacuum/commands/upgrade/)
- [apply-overlay](https://quobix.com/vacuum/commands/apply-overlay/)
- [schema](https://quobix.com/vacuum/commands/schema/)
- [Change Detection](https://quobix.com/vacuum/commands/change-detection/)
- [open-collection](https://quobix.com/vacuum/commands/open-collection/)
- [generate-ruleset](https://quobix.com/vacuum/commands/generate-ruleset/)
- [version](https://quobix.com/vacuum/commands/version/)
- [External References](https://quobix.com/vacuum/commands/external-references/)
- [Exit Codes](https://quobix.com/vacuum/commands/exit-codes/)
- [Developer API](https://quobix.com/vacuum/api/getting-started/)
- [Using The Index](https://quobix.com/vacuum/api/spec-index/)
- [RuleResultSet](https://quobix.com/vacuum/api/rule-resultset/)
- [Loading a RuleSet](https://quobix.com/vacuum/api/loading-ruleset/)
- [Linting Non-OpenAPI Files](https://quobix.com/vacuum/api/non-openapi/)
- [Custom Golang Functions](https://quobix.com/vacuum/api/custom-functions/)
- [Custom JavaScript Functions](https://quobix.com/vacuum/api/custom-javascript-functions/)
- [Rules](https://quobix.com/vacuum/rules/)
- [Examples](https://quobix.com/vacuum/rules/examples/)
- [Tags](https://quobix.com/vacuum/rules/tags/)
- [Descriptions](https://quobix.com/vacuum/rules/descriptions/)
- [Schemas](https://quobix.com/vacuum/rules/schemas/)
- [Spec Information](https://quobix.com/vacuum/rules/information/)
- [Operations & Paths](https://quobix.com/vacuum/rules/operations/)
- [Channels](https://quobix.com/vacuum/rules/channels/)
- [Messages](https://quobix.com/vacuum/rules/messages/)
- [Servers](https://quobix.com/vacuum/rules/servers/)
- [Validation](https://quobix.com/vacuum/rules/validation/)
- [Security](https://quobix.com/vacuum/rules/security/)
- [OWASP](https://quobix.com/vacuum/rules/owasp/)
- [Functions](https://quobix.com/vacuum/functions/)
- [Core Functions](https://quobix.com/vacuum/functions/core/)
- [OpenAPI Functions](https://quobix.com/vacuum/functions/openapi/)
- [OWASP Functions](https://quobix.com/vacuum/functions/owasp/)
- [AsyncAPI Functions](https://quobix.com/vacuum/functions/asyncapi/)
- [Understanding RuleSets](https://quobix.com/vacuum/rulesets/understanding/)
- [Sharing RuleSets](https://quobix.com/vacuum/rulesets/sharing/)
- [All Rules](https://quobix.com/vacuum/rulesets/all/)
- [No Rules](https://quobix.com/vacuum/rulesets/no-rules/)
- [Recommended Rules](https://quobix.com/vacuum/rulesets/recommended/)
- [AsyncAPI Default Rules](https://quobix.com/vacuum/rulesets/asyncapi-recommended/)
- [AsyncAPI All Rules](https://quobix.com/vacuum/rulesets/asyncapi/)
- [Custom Rules](https://quobix.com/vacuum/rulesets/custom-rulesets/)
---
> **vacuum can suck all the lint of a 5mb API description in milliseconds.**
Designed to reliably lint API descriptions, **very, very quickly**. Including _very large_ ones. Spectral can be quite slow
when used as an API and does not scale for enterprise applications.
vacuum will tell you what is wrong with your spec, why, where, and how to fix it.
vacuum will work at scale and is designed as a CLI (with a web or console UI) and a library to be consumed in other applications.
### 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.
<a href="https://quobix.com/vacuum/commands/dashboard/">
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/dashboard.gif">
<img alt="dashboard" src=".github/assets/dashboard.gif">
</picture>
</a>
To read about the dashboard, see the [dashboard command docs](https://quobix.com/vacuum/commands/dashboard/).
### 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.
---
> **_Supports OpenAPI Version 2, OpenAPI Version 3+, AsyncAPI 3, and JSON Schema documents_**
You can use either **YAML** or **JSON**, vacuum supports both formats.
## Using vacuum with pre-commit
vacuum can be used with [pre-commit](https://pre-commit.com).
To do that, add to your `.pre-commit-config.yaml`:
```yaml
repos:
- repo: https://github.com/daveshanley/vacuum
rev: # a tag or a commit hash from this repo, see https://github.com/daveshanley/vacuum/releases
hooks:
- id: vacuum
```
See the [hook definition](./.pre-commit-hooks.yaml) here for details on what options the hook uses and what files it checks by default.
If no filenames or more than one filename in your repository matches the default `files` pattern in the hook definition,
the pattern needs to be overridden in your config so that it matches exactly one filename to lint at a time.
To lint multiple files, specify the hook multiple times with the appropriate overrides.
## 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`
## Generate a Spectral compatible report
If you're already using Spectral JSON reports, and you want to use vacuum instead, use the `spectral-report` command
```
./vacuum spectral-report <your-openapi-spec.yaml> <report-output-name.json>
```
The report file name is _optional_. The default report output name is `vacuum-spectral-report.json`
## Generate a `vacuum report`
vacuum reports are complete snapshots in time of a linting report for a specification. These reports can be 'replayed'Frequently Asked Questions
What is vacuum?
vacuum is a Code Analysis library for the Go programming language. An ultra-super-fast, lightweight OpenAPI linter and quality checking tool
How many GitHub stars does vacuum have?
vacuum has 1,138 GitHub stars in the directory's latest synchronization.
How do I install vacuum?
Install vacuum with the Go module system using `go get daveshanley/vacuum`. Check the repository for the current installation instructions.
What category does vacuum belong to?
vacuum is listed under Code Analysis, specifically Code Analysis.