If the OpenAPI specifcation being processed by
vacuum contains external references, then
vacuum will need to know
how to handle them when resolving the specification.
References come in three forms:
- Local references
- Remote references
- Relative references
Local references are those that are local to the specification being processed. They look something like this:
They are local in the sense that they are contained within the same document as the reference.
vaccum knows how to handle these references out of the box, without needing any further configuration.
Remote references are those that are hosted on a remote server, and are accessed via a URL. They look something like this:
The first part (before the hash) is the full URL to the remote file. The second part (after the hash) is the JSON Pointer to the object being referenced.
This is the correct way to reference remote files, vacuum will support this out of the box, without needing any further configuration.
However, this is generally not the way that remote references are used in the wild.
Most of the time an OpenAPI specification assumes you have downloaded the entire set of files from the remote location, before you start processing the specification, which is not a good assumption to make.
Relative references can be those that are hosted on a remote server, or on the local file system. They can be either!
So how does vacuum know the difference?
For example, when parsing the Digital Ocean specification, there are references to relative files that are hosted on the remote server.
This isn’t very useful if the indexing engine tries to find those files on the local file system (which is what the specification is indicating) and it can’t.
Providing a BaseURL
To solve this problem,
vacuum allows you to provide a
BaseURL that will be used to resolve relative references.
This URL is used by the resolver to resolve relative references correctly if they do not exist on the local file system.
This is done using the
In the Digital Ocean
BaseURL would be https://raw.githubusercontent.com/digitalocean/openapi/main/specification
vacuum lint digitalocean.yaml -p \ https://raw.githubusercontent.com/digitalocean/openapi/main/specification
Providing a Base working directory
If files are available locally, then you can provide a base working directory that will be used to resolve relative references. This directory is used by the resolver to resolve relative references correctly if they do exist on the local file system.
The default is the current working directory, however it can be set to anything using the same
The index will look in
../../specs/openapi as a base for relative files.
If you just want vacuum to figure out where to look for remote files, or local files then just use the
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.