From 16403633fd1fbd6dbcb738af55946ddbdc3603e3 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Thu, 10 Oct 2024 12:15:00 -0700 Subject: [PATCH 1/2] Note relative URL-reference resolution ambiguity This explicitly lists out the cases and notes which ones were (as far as we can recall) intended to behave like `$ref`, but could be reasonably read to behave like API URLs. --- versions/3.0.4.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 82a7963e0f..ae79e0f18d 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -232,10 +232,15 @@ OpenAPI Description authors SHOULD consider how text using such extensions will ### Relative References in URLs Unless specified otherwise, all fields that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2). + Relative references are resolved using the URLs defined in the [Server Object](#server-object) as a Base URI. Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#reference-object). +The wording above is intended to distinguish between API URLs (which use the Server Object to determine the base URI or the prefix for the URL path template), and OAD URLs (which use the current document's base URI per RFC3986). +However, only `$ref` was mentioned explicitly in versions 3.0.0 through 3.0.3 of this specification, leaving the behavior of the following fields ambiguous: the `operationRef` field of the [Link Object](#link-object), the URI form of the `mapping` field of the [Discriminator Object](#discriminator-object), the `externalValue` field of the [Example Object](#example-object), and the `url` fields of the [External Documentation](#external-documentation-object), [Contact](#contact-object), and [License](#license-object) Objects. +Therefore, which of the above two rules is used for each of these fields is _implementation-defined_, although it is RECOMMENDED to use the `$ref` process for all of them for compatibility with future versions of this specification. + Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description. ### Schema From 5cb6de9c08bddaafcca60c696a3aab08272968fd Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 11 Oct 2024 12:42:20 -0700 Subject: [PATCH 2/2] Improve wording from review feedback Co-authored-by: Mike Kistler --- versions/3.0.4.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index ae79e0f18d..5329c824b1 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -237,9 +237,7 @@ Relative references are resolved using the URLs defined in the [Server Object](# Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), using the URL of the current document as the base URI. See also the [Reference Object](#reference-object). -The wording above is intended to distinguish between API URLs (which use the Server Object to determine the base URI or the prefix for the URL path template), and OAD URLs (which use the current document's base URI per RFC3986). -However, only `$ref` was mentioned explicitly in versions 3.0.0 through 3.0.3 of this specification, leaving the behavior of the following fields ambiguous: the `operationRef` field of the [Link Object](#link-object), the URI form of the `mapping` field of the [Discriminator Object](#discriminator-object), the `externalValue` field of the [Example Object](#example-object), and the `url` fields of the [External Documentation](#external-documentation-object), [Contact](#contact-object), and [License](#license-object) Objects. -Therefore, which of the above two rules is used for each of these fields is _implementation-defined_, although it is RECOMMENDED to use the `$ref` process for all of them for compatibility with future versions of this specification. +It is _implementation_defined_ whether the resolution of relative references in each of the `operationRef` field of the [Link Object](#link-object), the URI form of the `mapping` field of the [Discriminator Object](#discriminator-object), the `externalValue` field of the [Example Object](#example-object), and the `url` fields of the [External Documentation](#external-documentation-object), [Contact](#contact-object), and [License](#license-object) Objects resolve by using the same process as `$ref` or by using the Server Object. For compatibility with future versions of this specification, the `$ref` process is RECOMMENDED for all of these fields. Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description.