Skip to content

Commit db9f643

Browse files
handrewshandrews
committed
Move base URI examples to appendix
1 parent 71ec162 commit db9f643

File tree

1 file changed

+144
-144
lines changed

1 file changed

+144
-144
lines changed

‎src/oas.md

Lines changed: 144 additions & 144 deletions
Original file line numberDiff line numberDiff line change
@@ -344,156 +344,13 @@ Unless specified otherwise, all fields that are URIs MAY be relative references
344344

345345
#### Establishing the Base URI
346346

347-
Relative URI references are resolved using the appropriate base URI, which MUST be determined in accordance with [[RFC3986]] [Section 5.1.1 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.1) and, for Schema objects, [JSON Schema draft 2020-12 Section 8.2](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#section-8.2), as illustrated by the examles below.
347+
Relative URI references are resolved using the appropriate base URI, which MUST be determined in accordance with [[RFC3986]] [Section 5.1.1 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.1) and, for Schema objects, [JSON Schema draft 2020-12 Section 8.2](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#section-8.2), as illustrated by the examles in [Appendix G: Examples of Base URI Determination and Reference Resolution](#appendix-g-examples-of-base-uri-determination-and-reference-resolution).
348348

349349
The most common base URI source in the absence of the [OpenAPI Object's](#openapi-object) `$self` or the [Schema Object's](#schema-object) `$id` is the retrieval URI.
350350
Implementations MAY support document retrieval, although see the [Security Considerations](#security-considerations) sections for additional guidance.
351351
Even if retrieval is supported, it may be impossible due to network configuration or server unavailability (including the server hosting an older version while a new version is in development), or undesirable due to performance impacts.
352352
Therefore, all implementations SHOULD allow users to provide the intended retrieval URI for each document so that references can be resolved as if retrievals were performed.
353353

354-
##### Examples of Base URI Determination and Reference Resolution
355-
356-
###### Base URI Within Content
357-
358-
A base URI within the resource's content (RFC3986 Section 5.1.1) is the highest-precedence source of a base URI.
359-
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:
360-
361-
```YAML
362-
openapi: 3.2.0
363-
$self: https://example.com/openapi
364-
info:
365-
title: Example API
366-
version: 1.0
367-
components:
368-
requestBodies:
369-
Foo:
370-
content:
371-
application/json:
372-
schema:
373-
$ref: schemas/foo
374-
schemas:
375-
Foo:
376-
$id: https://example.com/api/schemas/foo
377-
properties:
378-
bar:
379-
$ref: bar
380-
Bar:
381-
$id: https://example.com/api/schemas/bar
382-
type: string
383-
```
384-
385-
In the example above, the `$ref` in the Request Body Object is resolved using `$self` as the base URI, producing `https://example.com/schemas/foo`.
386-
This matches the `$id` at `#/components/schemas/Foo/$id` so it points to that Schema Object.
387-
That Schema Object has a subschema with `$ref: bar`, which is resolved against the `$id` to produce `https://example.com/schemas/bar`, which matches the `$id` at `#/components/schemas/Bar/$id`.
388-
389-
Note that referring to a schema with a JSON Pointer that crosses a Schema Object with a `$id` [is not interoperable](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#name-json-pointer-fragments-and-).
390-
The JSON Schema specification does not address the case of using a pointer _to_ a Schema Object containing an `$id` without crossing into that Schema Object.
391-
Therefore it is RECOMMENDED that OAD authors use `$id` values to reference such schemas rather than JSON Pointers.
392-
393-
Note also that it is impossible for the reference at `#/components/schemas/Foo/properties/bar/$ref` to reference the schema at `#/components/schemas/Bar` using a JSON Pointer, as the JSON Pointer would be resolved relative to `https://example.com/schemas/foo`, not to the OpenAPI Document's base URI from `$self`.
394-
395-
396-
###### Base URI From Encapsulating Entity
397-
398-
If no base URI can be determined within the content, the next ___location to search is any encapsulating entity (RFC3986 Section 5.1.2).
399-
400-
This is common for Schema Objects encapsulated within an OpenAPI Document.
401-
An example of an OpenAPI Document 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.
402-
Note that this is purely an example, and support for such multipart documents or any other format that could encapsulate an OpenAPI Document is not a requirement of this specification.
403-
404-
```MULTIPART
405-
--boundary-example
406-
Content-Type: application/openapi+yaml
407-
Content-Location: https://inaccessible-___domain.com/api/openapi.yaml
408-
409-
openapi: 3.2.0
410-
info:
411-
title: Example API
412-
version: 1.0
413-
externalDocs:
414-
url: docs.html
415-
components:
416-
requestBodies:
417-
Foo:
418-
content:
419-
application/json:
420-
schema:
421-
$ref: "#/components/api/schemas/Foo"
422-
schemas:
423-
Foo:
424-
properties:
425-
bar:
426-
$ref: schemas/bar
427-
--boundary-example
428-
Content-Type: application/schema+json; schema=https://spec.openapis.org/oas/3.2/schema-base/YYYY-MM-DD
429-
Content-Location: https://example.com/api/schemas/bar
430-
431-
{
432-
"type": "string"
433-
}
434-
--boundary-example
435-
Content-Type: text/html
436-
Content-Location: https://example.com/api/docs.html
437-
438-
<html>
439-
<head>
440-
<title>API Documentation</title>
441-
</head>
442-
<body>
443-
<p>Awesome documentation goes here</p>
444-
</body>
445-
</html>
446-
--boundary-example
447-
```
448-
449-
In this example, the URI for each part, which also serves as its base URI, comes from the part's `Content-Location` header as specified by RFC2557.
450-
Since the Schema Object at `#/components/schemas/Foo` does not contain an `$id`, the reference in its subschema uses the OpenAPI Document's base URI, which is taken from the `Content-Location` header of its part within the `multipart/related` format.
451-
The resulting reference to `https://example.com/schemas/bar` matches the `Content-Location` header of the second part, which allows the reference target to be located within the multipart archive.
452-
453-
Similarly, the `url` field of the [External Documentation Object](#external-documentation-object) is resolved against the base URI from `Content-Location`, producing `https://example.com/api/docs.html` which matches the `Content-Location` of the third part.
454-
455-
###### Base URI From the Retrieval URI
456-
457-
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).
458-
459-
For this example, assume that the YAML OpenAPI Document was retrieved from `https://example.com/api/openapis.yaml` and the JSON Schema document from `https://example.com/api/schemas/foo`
460-
461-
Assume this document was retrieved from `https://example.com/api/openapis.yaml`:
462-
463-
```YAML
464-
openapi: 3.2.0
465-
info:
466-
title: Example API
467-
version: 1.0
468-
components:
469-
requestBodies:
470-
Foo:
471-
content:
472-
application/json:
473-
schema:
474-
$ref: schemas/foo
475-
```
476-
477-
Assume this document was retrieved from `https://example.com/api/schemas/foo`:
478-
479-
```JSON
480-
{
481-
"type": "object",
482-
"properties": {
483-
"bar": {
484-
"type": "string"
485-
}
486-
}
487-
}
488-
```
489-
490-
Resolving the `$ref: schemas/foo` against the retrieval URI of the OpenAPI Document produces `https://example.com/api/schemas/foo`, the retrieval URI of the JSON Schema document.
491-
492-
###### Application-Specific Default Base URI
493-
494-
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).
495-
While this sort of internal resolution an be performed in practice without choosing a base URI, choosing one avoids the need to implement it as a special case.
496-
497354
#### Resolving URI fragments
498355

499356
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901](https://tools.ietf.org/html/rfc6901).
@@ -5338,3 +5195,146 @@ components:
53385195
```
53395196

53405197
In the `other` document, the referenced path item has a Security Requirement for a Security Scheme, `MySecurity`. The same Security Scheme exists in the original entry document. As outlined in [Resolving Implicit Connections](#resolving-implicit-connections), `MySecurity` is resolved with an [implementation-defined behavior](#undefined-and-implementation-defined-behavior). However, documented in that section, it is RECOMMENDED that tools resolve component names from the [entry document](#openapi-description-structure). As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.
5198+
5199+
## Appendix G: Examples of Base URI Determination and Reference Resolution
5200+
5201+
### Base URI Within Content
5202+
5203+
A base URI within the resource's content (RFC3986 Section 5.1.1) is the highest-precedence source of a base URI.
5204+
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:
5205+
5206+
```YAML
5207+
openapi: 3.2.0
5208+
$self: https://example.com/openapi
5209+
info:
5210+
title: Example API
5211+
version: 1.0
5212+
components:
5213+
requestBodies:
5214+
Foo:
5215+
content:
5216+
application/json:
5217+
schema:
5218+
$ref: schemas/foo
5219+
schemas:
5220+
Foo:
5221+
$id: https://example.com/api/schemas/foo
5222+
properties:
5223+
bar:
5224+
$ref: bar
5225+
Bar:
5226+
$id: https://example.com/api/schemas/bar
5227+
type: string
5228+
```
5229+
5230+
In the example above, the `$ref` in the Request Body Object is resolved using `$self` as the base URI, producing `https://example.com/schemas/foo`.
5231+
This matches the `$id` at `#/components/schemas/Foo/$id` so it points to that Schema Object.
5232+
That Schema Object has a subschema with `$ref: bar`, which is resolved against the `$id` to produce `https://example.com/schemas/bar`, which matches the `$id` at `#/components/schemas/Bar/$id`.
5233+
5234+
Note that referring to a schema with a JSON Pointer that crosses a Schema Object with a `$id` [is not interoperable](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#name-json-pointer-fragments-and-).
5235+
The JSON Schema specification does not address the case of using a pointer _to_ a Schema Object containing an `$id` without crossing into that Schema Object.
5236+
Therefore it is RECOMMENDED that OAD authors use `$id` values to reference such schemas rather than JSON Pointers.
5237+
5238+
Note also that it is impossible for the reference at `#/components/schemas/Foo/properties/bar/$ref` to reference the schema at `#/components/schemas/Bar` using a JSON Pointer, as the JSON Pointer would be resolved relative to `https://example.com/schemas/foo`, not to the OpenAPI Document's base URI from `$self`.
5239+
5240+
5241+
### Base URI From Encapsulating Entity
5242+
5243+
If no base URI can be determined within the content, the next ___location to search is any encapsulating entity (RFC3986 Section 5.1.2).
5244+
5245+
This is common for Schema Objects encapsulated within an OpenAPI Document.
5246+
An example of an OpenAPI Document 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.
5247+
Note that this is purely an example, and support for such multipart documents or any other format that could encapsulate an OpenAPI Document is not a requirement of this specification.
5248+
5249+
```MULTIPART
5250+
--boundary-example
5251+
Content-Type: application/openapi+yaml
5252+
Content-Location: https://inaccessible-___domain.com/api/openapi.yaml
5253+
5254+
openapi: 3.2.0
5255+
info:
5256+
title: Example API
5257+
version: 1.0
5258+
externalDocs:
5259+
url: docs.html
5260+
components:
5261+
requestBodies:
5262+
Foo:
5263+
content:
5264+
application/json:
5265+
schema:
5266+
$ref: "#/components/api/schemas/Foo"
5267+
schemas:
5268+
Foo:
5269+
properties:
5270+
bar:
5271+
$ref: schemas/bar
5272+
--boundary-example
5273+
Content-Type: application/schema+json; schema=https://spec.openapis.org/oas/3.2/schema-base/YYYY-MM-DD
5274+
Content-Location: https://example.com/api/schemas/bar
5275+
5276+
{
5277+
"type": "string"
5278+
}
5279+
--boundary-example
5280+
Content-Type: text/html
5281+
Content-Location: https://example.com/api/docs.html
5282+
5283+
<html>
5284+
<head>
5285+
<title>API Documentation</title>
5286+
</head>
5287+
<body>
5288+
<p>Awesome documentation goes here</p>
5289+
</body>
5290+
</html>
5291+
--boundary-example
5292+
```
5293+
5294+
In this example, the URI for each part, which also serves as its base URI, comes from the part's `Content-Location` header as specified by RFC2557.
5295+
Since the Schema Object at `#/components/schemas/Foo` does not contain an `$id`, the reference in its subschema uses the OpenAPI Document's base URI, which is taken from the `Content-Location` header of its part within the `multipart/related` format.
5296+
The resulting reference to `https://example.com/schemas/bar` matches the `Content-Location` header of the second part, which allows the reference target to be located within the multipart archive.
5297+
5298+
Similarly, the `url` field of the [External Documentation Object](#external-documentation-object) is resolved against the base URI from `Content-Location`, producing `https://example.com/api/docs.html` which matches the `Content-Location` of the third part.
5299+
5300+
### Base URI From the Retrieval URI
5301+
5302+
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).
5303+
5304+
For this example, assume that the YAML OpenAPI Document was retrieved from `https://example.com/api/openapis.yaml` and the JSON Schema document from `https://example.com/api/schemas/foo`
5305+
5306+
Assume this document was retrieved from `https://example.com/api/openapis.yaml`:
5307+
5308+
```YAML
5309+
openapi: 3.2.0
5310+
info:
5311+
title: Example API
5312+
version: 1.0
5313+
components:
5314+
requestBodies:
5315+
Foo:
5316+
content:
5317+
application/json:
5318+
schema:
5319+
$ref: schemas/foo
5320+
```
5321+
5322+
Assume this document was retrieved from `https://example.com/api/schemas/foo`:
5323+
5324+
```JSON
5325+
{
5326+
"type": "object",
5327+
"properties": {
5328+
"bar": {
5329+
"type": "string"
5330+
}
5331+
}
5332+
}
5333+
```
5334+
5335+
Resolving the `$ref: schemas/foo` against the retrieval URI of the OpenAPI Document produces `https://example.com/api/schemas/foo`, the retrieval URI of the JSON Schema document.
5336+
5337+
### Application-Specific Default Base URI
5338+
5339+
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).
5340+
While this sort of internal resolution an be performed in practice without choosing a base URI, choosing one avoids the need to implement it as a special case.

0 commit comments

Comments
 (0)