Handling References

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.

Reference Types

References come in three forms:

• Local references
• Remote references
• Relative references

Local references

Local references are those that are local to the specification being processed. They look something like this:

$ref: '#/components/schemas/Error'

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

Remote references are those that are hosted on a remote server, and are accessed via a URL. They look something like this:

$ref: 'https://api.quobix.com/openapi.yaml#/components/schemas/Error'

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

Relative references can be those that are hosted on a remote server, or on the local file system. They can be either!

$ref: '../../../resources/openapi.yaml#/components/schemas/Error'

So how does vacuum know the difference?

It doesn’t!

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 -p / --base flag.

In the Digital Ocean example, the BaseURL would be https://raw.githubusercontent.com/digitalocean/openapi/main/specification

For example

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 -p / --base flag.

The index will look in ../../specs/openapi as a base for relative files.

Automatic mode

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: