OpenApi 3.1: URL resolving

[char0n]

OAS 3.1 defines two relative reference resolution mechanisms:

Relative References in URIs

This is already handled by external resolution and dereference mechanisms.

Relative References in URLs

Unless specified otherwise, all properties that are URLs MAY be relative references as defined by RFC3986. Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.

Server Objects can be defined in following specification objects:

• OpenAPI Object (servers field)
• Path Item Object (servers field)
• Operation Object (servers field)
• Link Object (server field)

OpenApi.servers has one specific of defaulting to default Server Object with special value of url field:

An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.

Paths Object has a specific way of appending /{path} pattern field to Server Objects rather than using resolution:

A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object's url field in order to construct the full URL. Path templating is allowed.

All this technically means that all specification objects fields that contains This MUST be in the form of a URL text must comply with resolution as specified in this section.

If Server Object contains variables, these variables needs to be transcluded into url field before Server Object is used for URL resolution.

If Server Object contain relative url field, this field need to be resolved using document baseURI.

There might be various situations during URL resolution:

1. Multiple Server Objects are defined on multiple levels of definition file. In order to resolve all relative URLs one needs to be specified which sets the baseURL for all URL resolutions. Here the question is which of the multiple Server Objects will be used for URL resolution? I think only sensible answer to that is to pass Server Object itself or it's url field as a parameter to URL resolution explicitly; if we use random Server Object it may not be the one that user wants.
2. If one Server Object is defined in definition file we can detected that and implicitly use that one. Problem here is that to detect the Server Object we'd have to traverse entire definition file before we begin with URL resolution.
3. If no Server Object is defined in definition file, default Server Object with special value of url field is computed and used. This requires to detected that there are no Server Objects defined, which requires additional traversal of entire definition file before we begin with URL resolution.

To unify all these situation and keep the performance to sensible levels i suggest following:

• make URL resolution part of dereference (keeping one single traversal pass)
• provide Server Object or Server Object url field as explicit parameter to dereferencing (if no is provided, default Server Object url is assumed)
• all URL resolution will be done use that explicit parameter

For the purpose of servers field override in Path Item and Operation objects, we can pick first Server Object defined there and just use it. This is based on an assumption that all these servers should have resolved URLs returning the same resource, so it doesn't really matter which one we use. But for the sake of simplicity of first implementation this can be implemented later in progressive manner.