vacuum can add missing descriptions, generate examples, remove duplicates and repair supported structural problems.
You review the changes before they are written. Use the console to review a batch. Use the dashboard to inspect each fix and edit its value.
Preview without writing
vacuum checks the fixes in memory and shows a diff: red for removals, green for additions. Declined fixes include a reason.
No files are written. The lint report and exit code still describe the original file. A dry run cannot make a failing spec pass CI.
Fix from the console
- Select the fixes.
- Review the diff and contract impact.
- Enter to apply. Esc to cancel.
Enter fix numbers separated by spaces, or press Enter to review all. For a long diff, press d to see all changes. vacuum lists any fixes it cannot verify.
Check the contract impact before you apply. A failed verification cannot be accepted.
To write a separate file after review:
For JSON Schema:
Review and edit in the dashboard
Press f to find available fixes. Nothing starts selected.
Press Enter to open Currently / Autofixed: source on the left, proposed fix on the right. Only changed lines get blue or yellow highlights. The rest keeps its syntax colors.
Press e to edit a value in the modal. Enter saves the proposal; Esc cancels the edit.
| Key | In fix review |
|---|---|
| ↑ / ↓ | Move between fixes |
| Enter | Open a proposal; select or deselect it in Currently / Autofixed |
| Space | Select or deselect a fix |
| e | Edit a supported value |
| v | Verify the displayed proposal, or the selected batch from the fix list |
| a | Save selected fixes |
| ← / → | Pan long source lines |
| PgUp / PgDn | Scroll the proposal |
| Esc | Go back |
Verification shows the changes and contract impact. Use [ / ] to move between changes; t opens the full diff. Verifying a proposal does not select it.
Save the selected fixes
Press a. Update the source, create a new specification, or save an OpenAPI overlay.
When saving a specification, choose how to handle references. OpenAPI 3 supports keeping, inlining or composing references. Review the output, fix count and score, then press Enter to save.
Save as an overlay
Choose Save as an overlay to keep the fixes in a separate file. For api.yaml, vacuum suggests
api.overlay.yaml beside the source. Use a .json filename for a JSON overlay.
The left pane shows the overlay actions. The right pane shows the resulting specification. Press Tab to switch panes, then use the arrow keys to scroll or pan. Use [ and ] to jump between changed lines when locations are available.
vacuum applies the overlay in memory and checks that it produces the reviewed result. Press Enter to save the overlay or Esc to cancel. The source keeps its original references.
To apply the saved fixes later, run:
See Apply Overlay for overlay actions, examples and command options.
What can be fixed?
Only enabled rules offer fixes. The finding and source structure determine which fixes are available.
| Area | Supported fixes include |
|---|---|
| Descriptions and metadata | Add missing descriptions, contact and license details |
| Examples | Generate missing examples or replace invalid ones with checked schema-derived values |
| Operations and tags | Add tags and unique operation IDs |
| Schemas | Deduplicate enums, simplify single-item compositions and correct type constraints |
| Paths and names | Order paths, normalize names and remove trailing slashes |
| Unused content | Remove unreferenced components or definitions |
Review generated descriptions and examples for accuracy. To supply your own values, use an autofix policy.
What gets checked?
vacuum runs the rules again. Selected findings must be resolved, with no new findings, structural errors, broken references or invalid IDs. Ignore rules follow their original nodes when items move.
Renaming paths, removing components and changing schema constraints can break the contract. For supported OpenAPI documents, libopenapi checks for breaking changes. The result can also be unknown if comparison is unavailable or cannot finish. Both breaking changes and unknown impact need your acceptance.
Only the root file is written. Untouched text is preserved, and vacuum checks the source again before saving. Edits it cannot preserve are declined.
CI and limits
Use --fix --dry-run in CI. Without an interactive terminal, --fix reports the original findings and
writes nothing. Structured reports go to stdout; review text goes to stderr.
Fixes need a local source file. Saved reports, remote URLs and the dashboard’s --original and --changes
views are read-only. AsyncAPI repair does not support external references.
vacuum declines unsupported anchors, aliases, duplicate keys, reference-sensitive array edits and multi-document YAML. Custom fix callbacks are outside this CLI flow.