Frequently Asked Questions

Q: Can I use this in production?

Yes. It’s being used by multiple 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:

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:

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:

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.