Skip to content

Commit 47c3194

Browse files
handrewshandrews
committed
Move base URI examples to appendix
1 parent 4225262 commit 47c3194

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
@@ -310,156 +310,13 @@ Unless specified otherwise, all fields that are URIs MAY be relative references
310310

311311
#### Establishing the Base URI
312312

313-
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.
313+
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).
314314

315315
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.
316316
Implementations MAY support document retrieval, although see the [Security Considerations](#security-considerations) sections for additional guidance.
317317
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.
318318
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.
319319

320-
##### Examples of Base URI Determination and Reference Resolution
321-
322-
###### Base URI Within Content
323-
324-
A base URI within the resource's content (RFC3986 Section 5.1.1) is the highest-precedence source of a base URI.
325-
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:
326-
327-
```YAML
328-
openapi: 3.2.0
329-
$self: https://example.com/openapi
330-
info:
331-
title: Example API
332-
version: 1.0
333-
components:
334-
requestBodies:
335-
Foo:
336-
content:
337-
application/json:
338-
schema:
339-
$ref: schemas/foo
340-
schemas:
341-
Foo:
342-
$id: https://example.com/api/schemas/foo
343-
properties:
344-
bar:
345-
$ref: bar
346-
Bar:
347-
$id: https://example.com/api/schemas/bar
348-
type: string
349-
```
350-
351-
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`.
352-
This matches the `$id` at `#/components/schemas/Foo/$id` so it points to that Schema Object.
353-
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`.
354-
355-
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-).
356-
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.
357-
Therefore it is RECOMMENDED that OAD authors use `$id` values to reference such schemas rather than JSON Pointers.
358-
359-
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`.
360-
361-
362-
###### Base URI From Encapsulating Entity
363-
364-
If no base URI can be determined within the content, the next location to search is any encapsulating entity (RFC3986 Section 5.1.2).
365-
366-
This is common for Schema Objects encapsulated within an OpenAPI Document.
367-
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.
368-
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.
369-
370-
```MULTIPART
371-
--boundary-example
372-
Content-Type: application/openapi+yaml
373-
Content-Location: https://inaccessible-domain.com/api/openapi.yaml
374-
375-
openapi: 3.2.0
376-
info:
377-
title: Example API
378-
version: 1.0
379-
externalDocs:
380-
url: docs.html
381-
components:
382-
requestBodies:
383-
Foo:
384-
content:
385-
application/json:
386-
schema:
387-
$ref: "#/components/api/schemas/Foo"
388-
schemas:
389-
Foo:
390-
properties:
391-
bar:
392-
$ref: schemas/bar
393-
--boundary-example
394-
Content-Type: application/schema+json; schema=https://spec.openapis.org/oas/3.2/schema-base/YYYY-MM-DD
395-
Content-Location: https://example.com/api/schemas/bar
396-
397-
{
398-
"type": "string"
399-
}
400-
--boundary-example
401-
Content-Type: text/html
402-
Content-Location: https://example.com/api/docs.html
403-
404-
<html>
405-
<head>
406-
<title>API Documentation</title>
407-
</head>
408-
<body>
409-
<p>Awesome documentation goes here</p>
410-
</body>
411-
</html>
412-
--boundary-example
413-
```
414-
415-
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.
416-
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.
417-
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.
418-
419-
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.
420-
421-
###### Base URI From the Retrieval URI
422-
423-
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).
424-
425-
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`
426-
427-
Assume this document was retrieved from `https://example.com/api/openapis.yaml`:
428-
429-
```YAML
430-
openapi: 3.2.0
431-
info:
432-
title: Example API
433-
version: 1.0
434-
components:
435-
requestBodies:
436-
Foo:
437-
content:
438-
application/json:
439-
schema:
440-
$ref: schemas/foo
441-
```
442-
443-
Assume this document was retrieved from `https://example.com/api/schemas/foo`:
444-
445-
```JSON
446-
{
447-
"type": "object",
448-
"properties": {
449-
"bar": {
450-
"type": "string"
451-
}
452-
}
453-
}
454-
```
455-
456-
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.
457-
458-
###### Application-Specific Default Base URI
459-
460-
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).
461-
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.
462-
463320
#### Resolving URI fragments
464321

465322
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).
@@ -5063,3 +4920,146 @@ components:
50634920
```
50644921

50654922
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.
4923+
4924+
## Appendix G: Examples of Base URI Determination and Reference Resolution
4925+
4926+
### Base URI Within Content
4927+
4928+
A base URI within the resource's content (RFC3986 Section 5.1.1) is the highest-precedence source of a base URI.
4929+
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:
4930+
4931+
```YAML
4932+
openapi: 3.2.0
4933+
$self: https://example.com/openapi
4934+
info:
4935+
title: Example API
4936+
version: 1.0
4937+
components:
4938+
requestBodies:
4939+
Foo:
4940+
content:
4941+
application/json:
4942+
schema:
4943+
$ref: schemas/foo
4944+
schemas:
4945+
Foo:
4946+
$id: https://example.com/api/schemas/foo
4947+
properties:
4948+
bar:
4949+
$ref: bar
4950+
Bar:
4951+
$id: https://example.com/api/schemas/bar
4952+
type: string
4953+
```
4954+
4955+
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`.
4956+
This matches the `$id` at `#/components/schemas/Foo/$id` so it points to that Schema Object.
4957+
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`.
4958+
4959+
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-).
4960+
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.
4961+
Therefore it is RECOMMENDED that OAD authors use `$id` values to reference such schemas rather than JSON Pointers.
4962+
4963+
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`.
4964+
4965+
4966+
### Base URI From Encapsulating Entity
4967+
4968+
If no base URI can be determined within the content, the next location to search is any encapsulating entity (RFC3986 Section 5.1.2).
4969+
4970+
This is common for Schema Objects encapsulated within an OpenAPI Document.
4971+
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.
4972+
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.
4973+
4974+
```MULTIPART
4975+
--boundary-example
4976+
Content-Type: application/openapi+yaml
4977+
Content-Location: https://inaccessible-domain.com/api/openapi.yaml
4978+
4979+
openapi: 3.2.0
4980+
info:
4981+
title: Example API
4982+
version: 1.0
4983+
externalDocs:
4984+
url: docs.html
4985+
components:
4986+
requestBodies:
4987+
Foo:
4988+
content:
4989+
application/json:
4990+
schema:
4991+
$ref: "#/components/api/schemas/Foo"
4992+
schemas:
4993+
Foo:
4994+
properties:
4995+
bar:
4996+
$ref: schemas/bar
4997+
--boundary-example
4998+
Content-Type: application/schema+json; schema=https://spec.openapis.org/oas/3.2/schema-base/YYYY-MM-DD
4999+
Content-Location: https://example.com/api/schemas/bar
5000+
5001+
{
5002+
"type": "string"
5003+
}
5004+
--boundary-example
5005+
Content-Type: text/html
5006+
Content-Location: https://example.com/api/docs.html
5007+
5008+
<html>
5009+
<head>
5010+
<title>API Documentation</title>
5011+
</head>
5012+
<body>
5013+
<p>Awesome documentation goes here</p>
5014+
</body>
5015+
</html>
5016+
--boundary-example
5017+
```
5018+
5019+
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.
5020+
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.
5021+
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.
5022+
5023+
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.
5024+
5025+
### Base URI From the Retrieval URI
5026+
5027+
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).
5028+
5029+
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`
5030+
5031+
Assume this document was retrieved from `https://example.com/api/openapis.yaml`:
5032+
5033+
```YAML
5034+
openapi: 3.2.0
5035+
info:
5036+
title: Example API
5037+
version: 1.0
5038+
components:
5039+
requestBodies:
5040+
Foo:
5041+
content:
5042+
application/json:
5043+
schema:
5044+
$ref: schemas/foo
5045+
```
5046+
5047+
Assume this document was retrieved from `https://example.com/api/schemas/foo`:
5048+
5049+
```JSON
5050+
{
5051+
"type": "object",
5052+
"properties": {
5053+
"bar": {
5054+
"type": "string"
5055+
}
5056+
}
5057+
}
5058+
```
5059+
5060+
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.
5061+
5062+
### Application-Specific Default Base URI
5063+
5064+
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).
5065+
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)