Q: I looked at the Spectral docs and…

OK, number one FAQ.

vacuum is not Spectral

vacuum is a completely independent entity. I don’t work for SmartBear and I don’t use Spectral.

If you’re using Spectral (and switch to vacuum), you should know that your custom rules that use core functions should all work just fine. vacuum allows spectral rulesets to operate. vacuum’s ruleset is a superset of Spectral’s.

A superset is an extension of a compatible foundation, i.e. TypeScript is a superset of JavaScript.

If you’re calling built in Spectral rules that are missing in vacuum, or you’re seeing different severities returned from the ones you get in Spectral… It’s because vacuum is not Spectral.

For clarity: vacuum contains a lot of rules that are named the same, but the logic inside them is 100% different.

vacuum is a galaxy away from Spectral in terms of its design, construction, architecture and feature set. Spectral was my inspiration behind building it.

I did not build vacuum because Spectral is great.

I built it because Spectral fails hard when you need to use it for real, heavy production work and scale.

To to any question that starts with ‘Spectral’, The answer is. I don’t know. I don’t use it.

That being said, if you see a glitch in the behavior of vacuum, that is not glitched in Spectral. I would love to help fix it for you.

Q: is it ‘vacuum’ or ‘Vacuum’

It’s vacuum. No upper case V.

I know this is improper. However, you don’t type Vacuum in your terminal to run it.

All my tools are named in all lowercase, because that is what you type into the terminal to run them.

Q: Can I use this in production?

Yes. It’s being used by thousands of companies in production today.

Q: Are you actively supporting vacuum?

Yes! There is a lot more to come in the future. It’s an active project with a rich roadmap ahead of it.

Q: Can I sponsor you?

Yes. It’s most welcome and appreciated. please visit the sponsor page for more information.

Companies are encouraged to sponsor vacuum, as it’s a great way to show your support for the project, and get priority support for your issues.

Q: Why do I see a ’local lookups are not permitted’ warning?

This answer applies only to versions of vacuum v0.3 and below.

It’s probably also telling you to set AllowFileLookup to true in the configuration. What does this mean?

This is vacuum telling you that its detected a local file reference in the OpenAPI specification, and that it’s not going to resolve it without you explicitly telling it to.

This is a safety guard to prevent a run-away malicious resolving incident happening. If you remember Log4Shell You will understand why this is important.

To tell vacuum to resolve the local file, you need to use the -p or --base flag that tells vacuum where to resolve the local file from. You can use . If the file is in your current working directory.

For example:

vacuum lint openapi.yaml --base .

Q: Why do I see a ‘remote lookups are not permitted’ warning?

This answer applies only to versions of vacuum v0.3 and below.

It’s probably also telling you to set AllowRemoteLookup to true in the configuration. What does this mean?

Like with local references, telling you that its detected a remote file reference in the OpenAPI specification, and that it’s not going to resolve it without you explicitly telling it to.

Same reason as local lookups. Log4Shell is a lesson from history.

To tell vacuum to resolve the remote file, you need to use the -p or --base flag that tells vacuum where to resolve the remote reference from.

For example:

vacuum lint openapi.yaml --base https://somewhere/someplace/

Q: Can vacuum just look up remote/file based references by its self?

If you just want vacuum to figure out where to look for remote files, or local files then just use the -u / --remote flag. It will attempt to locate files locally from the current working directory, or will look up remote references from the remote location defined by the ref.

For example:

vacuum lint openapi.yaml --remote

In version v0.5.0 the --remote flag was set to true by default. It’s on out of the box.

Q: I see file errors from something called ‘rolodex’

In version v0.4 vacuum upgraded libopenapi, which introduced a new feature called ‘rolodex’. The rolodex is a customizable remote/local file system that keeps track of all references located outside the root document.

The rolodex is intelligent enough to know when a reference is a remote reference, or a local reference, and will try to load the files from the correct location.

By default, vacuum uses the current working directory as the starting point for all relative references. If the file cannot be found, the rolodex will let you know.

You can change the starting point/working directory for relative references by using the -p / --base flag.

Q: Can I lint multiple files at once?

Yes!

In version v0.5.0+ The lint command accepts multiple OpenAPI files as inputs, either as a glob pattern, or as a list of files.

Q: Can I use vacuum to lint non-OpenAPI documents?

Yes!

In version v0.2.7 a new Developer API was introduced that allows you to lint any document.

And a new global flag --skip-check / -k was introduced that allows you to skip the OpenAPI checks, which means any of the core functions can be used to lint any YAML or JSON document.

This is a community requested feature.