Skip to content

3.2 base uri: reference RFC3986 #4954

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 14, 2025
Merged

3.2 base uri: reference RFC3986 #4954

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/oas.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5222,7 +5222,7 @@ This section shows each of the four possible sources of base URIs, followed by a

### Base URI Within Content

A base URI within the resource's content (RFC3986 Section 5.1.1) is the highest-precedence source of a base URI.
A base URI within the resource's content ([RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1.1)) is the highest-precedence source of a base URI.
For OpenAPI documents, this source is the OpenAPI Object's `$self` field, while for Schema Objects that contain a `$id`, or are a subschema of a Schema Object containing a `$id`, the source is the `$id` field:

Assume the retrieval URI of the following document is `file://home/someone/src/api/openapi.yaml`:
Expand Down Expand Up @@ -5282,7 +5282,7 @@ Note also that it is impossible for the reference at `#/components/schemas/Foo/p

### Base URI From Encapsulating Entity

If no base URI can be determined within the content, the next location to search is any encapsulating entity (RFC3986 Section 5.1.2).
If no base URI can be determined within the content, the next location to search is any encapsulating entity ([RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1.2)).

This is common for Schema Objects encapsulated within an OpenAPI document.
An example of an OpenAPI Object itself being encapsulated in another entity would be a `multipart/related` archive ([[?RFC2557]]), such as the following `multipart/related; boundary="boundary-example"; type="application/openapi+yaml"` document.
Expand Down Expand Up @@ -5343,7 +5343,7 @@ Similarly, the `url` field of the [External Documentation Object](#external-docu

### Base URI From the Retrieval URI

If no base URI is provided from either of the previous sources, the next source is the retrieval URI (RFC 3986 Section 5.1.3).
If no base URI is provided from either of the previous sources, the next source is the retrieval URI ([RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1.3)).

Assume this document was retrieved from `https://example.com/api/openapis.yaml`:

Expand Down Expand Up @@ -5378,7 +5378,7 @@ Resolving the `$ref: schemas/foo` against the retrieval URI of the OpenAPI docum

### Application-Specific Default Base URI

When constructing an OpenAPI document in memory that does not have a `$self`, or an encapsulating entity, or a retrieval URI, applications can resolve internal (fragment-only) references by assuming a default base URI (RFC3986 Section 5.1.4).
When constructing an OpenAPI document in memory that does not have a `$self`, or an encapsulating entity, or a retrieval URI, applications can resolve internal (fragment-only) references by assuming a default base URI ([RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1.4)).
While this sort of internal resolution can be performed in practice without choosing a base URI, choosing one, such as a URN with a randomly generated UUID (e.g. `urn:uuid:f26cdaad-3193-4398-a838-4ecb7326c4c5`) avoids the need to implement it as a special case.

### Resolving Relative `$self` and `$id`
Expand Down