repository·main·Indexed 22 days ago
https://github.com/daveshanley/vacuumAn ultra-fast, lightweight linter and quality checking tool for OpenAPI, AsyncAPI, and JSON Schema. It is designed to be fully compatible with existing Spectral rulesets and supports custom Go plugins and JavaScript functions with async/await and Fetch API capabilities. Key features include a Turbo Mode for large specifications, an interactive dashboard, HTML report generation, and an apply-overlay command for non-destructive OpenAPI modifications.
Vacuum's custom JavaScript functions support async/await and a full implementation of the Fetch API. This allows your custom linting logic to perform remote API calls or asynchronous processing.
Additionally, Batch Mode is supported, allowing custom functions to receive the entire list of nodes at once rather than firing individually, which is ideal for sending data to an LLM or a remote API in a single request.
By default, go install does not include HTML report support because it cannot generate the required Webpack UI bundles. To enable vacuum html-report functionality in a custom build, you must:
./scripts/build-ui-assets.sh to generate assets.-tags html_report_ui flag.Vacuum provides two levels of control for how $ref pointers are handled during rule execution:
Per Rule (resolved): In YAML/JSON rulesets, resolved defaults to true.
true: given, matched nodes, Index, and SpecInfo are derived from the dereferenced document. context.Document remains unresolved for compatibility.false: The rule operates on the raw document. Use this if you need to inspect $ref nodes directly.Per Run (--resolve-all-refs): This flag forces every rule into resolved execution, overriding any resolved: false settings, and provides a fully resolved context.Document to rule functions.
Nested References:
Use --nested-refs-doc-context to handle split specifications where an external file contains a relative $ref. This ensures nested relative refs resolve from the referenced document rather than the root document.
rules:
response-has-content:
given: "$.paths[*][*].responses['404']"
resolved: false
then:
field: content
function: definedFor significant speed boosts and improved memory performance, especially on large specifications, you can enable Turbo Mode using the -T flag. This mode is optimized for high-speed processing of large files.
vacuum lint -T <your-openapi-spec.yaml>Vacuum provides a dedicated schema command for linting JSON Schema documents. This command unlocks a specific set of functions and rules designed exclusively for JSON Schema.
Use vacuum schema to run these specialized checks on your JSON Schema files.
vacuum schema <your-json-schema.json>Vacuum can generate a navigable, offline-capable HTML report to explore broken rules and violations in a web browser.
Note: If you installed vacuum via go install, the HTML report UI bundles are excluded. To use it from source, you must run ./scripts/build-ui-assets.sh and build with the -tags html_report_ui flag.
vacuum html-report <your-openapi-spec.yaml | vacuum-report.json.gz> <report-name.html>To use a custom Go plugin with vacuum, you must compile the plugin as a Go plugin module (.so) and then provide its path to the vacuum binary using the -f flag during linting.
Navigate to the plugin directory and use go build with the -buildmode=plugin flag, including all necessary source files:
go build -buildmode=plugin boot.go check_single_path.go useless_func.goEnsure the main vacuum binary is compiled from the repository root:
go build vacuum.goUse the -f flag to specify the directory containing your compiled plugin. vacuum will automatically locate the .so file within that directory.
./vacuum lint -r <ruleset_path> -f <plugin_directory_path> <target_file_path># Compile the plugin
go build -buildmode=plugin boot.go check_single_path.go useless_func.go
# Compile vacuum
cd ../../ && go build vacuum.go
# Run vacuum with the plugin
./vacuum lint -r rulesets/examples/sample-plugin-ruleset.yaml -f plugin/sample /path/to/openapi.yamlThe dashboard command provides an interactive console UI to explore rules and violations. This is designed to help you navigate large numbers of results without scrolling through thousands of lines of text.
vacuum dashboard <your-openapi-spec.yaml>Pull the vacuum Docker image. The image supports linux/amd64 and linux/arm64 (including Apple Silicon). You can use dshanley/vacuum from Docker Hub or ghcr.io/daveshanley/vacuum from GitHub Packages.
To run vacuum in a container, mount your current working directory to /work and use a relative path to your specification file.
docker pull dshanley/vacuum
docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>After building a custom binary, you can verify that the version information was correctly embedded using the following commands:
version command to see the version string.lint --help to see the full version banner, which includes the version and the compiled date.# Check version string
./vacuum version
# Check full version info in banner
./vacuum lint --help
# Expected banner output: version: <your-version> | compiled: <your-date>Install vacuum using the official Homebrew tap.
brew install --cask daveshanley/vacuum/vacuumTo see the full linting report including diagnostic details for a specification, use the lint command with the -d flag.
vacuum lint -d <your-openapi-spec.yaml>