Merge pull request #3838 from handrews/ref-uriurl-311

Clarify "URI" and "URL" meaning and usage (3.1.1)

Author: lornajane

versions/3.1.1.md

@@ -254,17 +254,26 @@ OAS < 3.1 | OAS 3.1 | Comments
 Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
 Where OpenAPI tooling renders rich text it MUST support, at a minimum, markdown syntax as described by [CommonMark 0.27](https://spec.commonmark.org/0.27/). Tooling MAY choose to ignore some CommonMark features to address security concerns. 
 
-### <a name="relativeReferencesURI"></a>Relative References in URIs
+### <a name="relativeReferencesURI"></a>Relative References in API Description URIs
+
+URIs used as references within an OpenAPI Description, or to external documentation or other supplementary information such as a license, are resolved as _identifiers_, and described by this specification as ***URIs***.
+As noted under [Parsing Documents](#parsingDocuments), this specification inherits JSON Schema draft 2020-12's requirements for loading documents and associating them with their expected URIs, which might not match their current location.
+This feature is used both for working in development or test environments without having to change the URIs, and for working within restrictive network configurations or security policies.
+
+Note that some URI fields are named `url` for historical reasons, but the descriptive text for those fields uses the correct "URI" terminology.
 
 Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
 
-Relative references, including those in [`Reference Objects`](#referenceObject), [`PathItem Object`](#pathItemObject) `$ref` fields, [`Link Object`](#linkObject) `operationRef` fields and [`Example Object`](#exampleObject) `externalValue` fields, are resolved using the referring document as the Base URI according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.2).
+Relative references in [`Schema Objects`](#schemaObject), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2).
+
+Relative URI references in other Objects, and in Schema Objects where no parent schema contains an `$id`, MUST be resolved using the referring document's base URI, which is determined in accordance with [RFC3986 §5.1.2 – 5.1.4](https://tools.ietf.org/html/rfc3986#section-5.1.2).
+In practice, this is usually the retrieval URI of the document, which MAY be determined based on either its current actual location or a user-supplied expected location.
 
 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).
 
-Relative references in [`Schema Objects`](#schemaObject), including any that appear as `$id` values, use the nearest parent `$id` as a Base URI, as described by [JSON Schema Specification Draft 2020-12](https://tools.ietf.org/html/draft-bhutton-json-schema-00#section-8.2).  If no parent schema contains an `$id`, then the Base URI MUST be determined according to [RFC3986](https://tools.ietf.org/html/rfc3986#section-5.1).
+### <a name="relativeReferencesURL"></a>Relative References in API URLs
 
-### <a name="relativeReferencesURL"></a>Relative References in URLs
+API endpoints are by definition accessed as locations, and are described by this specification as ***URLs***.
 
 Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
 Unless specified otherwise, relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URL. Note that these themselves MAY be relative to the referring document.
@@ -307,7 +316,7 @@ Field Name | Type | Description
 <a name="infoTitle"></a>title | `string` | **REQUIRED**. The title of the API.
 <a name="infoSummary"></a>summary | `string` | A short summary of the API.
 <a name="infoDescription"></a>description | `string` | A description of the API. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
-<a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of a URL.
+<a name="infoTermsOfService"></a>termsOfService | `string` | A URI for the Terms of Service for the API. This MUST be in the form of a URI.
 <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
 <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
 <a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
@@ -360,7 +369,7 @@ Contact information for the exposed API.
 Field Name | Type | Description
 ---|:---:|---
 <a name="contactName"></a>name | `string` | The identifying name of the contact person/organization.
-<a name="contactUrl"></a>url | `string` | The URL pointing to the contact information. This MUST be in the form of a URL.
+<a name="contactUrl"></a>url | `string` | The URI for to the contact information. This MUST be in the form of a URI.
 <a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -391,7 +400,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="licenseName"></a>name | `string` | **REQUIRED**. The license name used for the API.
 <a name="licenseIdentifier"></a>identifier | `string` | An [SPDX](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60) license expression for the API. The `identifier` field is mutually exclusive of the `url` field.
-<a name="licenseUrl"></a>url | `string` | A URL to the license used for the API. This MUST be in the form of a URL. The `url` field is mutually exclusive of the `identifier` field.
+<a name="licenseUrl"></a>url | `string` | A URI for the license used for the API. This MUST be in the form of a URI. The `url` field is mutually exclusive of the `identifier` field.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -831,7 +840,7 @@ The path itself is still exposed to the documentation viewer but they will not k
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="pathItemRef"></a>$ref | `string` | Allows for a referenced definition of this path item. The referenced structure MUST be in the form of a [Path Item Object](#pathItemObject).  In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relativeReferencesURI). <br><br>**Deprecated:** Usage of the `$ref` property has been deprecated when accompanied with properties other than `summary` and `description`.
+<a name="pathItemRef"></a>$ref | `string` | Allows for a referenced definition of this path item. The value MUST be in the form of a URI, and the referenced structure MUST be in the form of a [Path Item Object](#pathItemObject).  In case a Path Item Object field appears both in the defined object and the referenced object, the behavior is undefined. See the rules for resolving [Relative References](#relativeReferencesURI). <br><br>**Deprecated:** Usage of the `$ref` property has been deprecated when accompanied with properties other than `summary` and `description`.
 <a name="pathItemSummary"></a>summary| `string` | An optional string summary, intended to apply to all operations in this path.
 <a name="pathItemDescription"></a>description | `string` | An optional string description, intended to apply to all operations in this path. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="pathItemGet"></a>get | [Operation Object](#operationObject) | A definition of a GET operation on this path.
@@ -1075,7 +1084,7 @@ Allows referencing an external resource for extended documentation.
 Field Name | Type | Description
 ---|:---:|---
 <a name="externalDocDescription"></a>description | `string` | A description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
-<a name="externalDocUrl"></a>url | `string` | **REQUIRED**. The URL for the target documentation. This MUST be in the form of a URL.
+<a name="externalDocUrl"></a>url | `string` | **REQUIRED**. The URI for the target documentation. This MUST be in the form of a URI.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -2065,7 +2074,7 @@ Field Name | Type | Description
 <a name="exampleSummary"></a>summary | `string` | Short description for the example.
 <a name="exampleDescription"></a>description | `string` | Long description for the example. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="exampleValue"></a>value | Any | Embedded literal example. The `value` field and `externalValue` field are mutually exclusive. To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.
-<a name="exampleExternalValue"></a>externalValue | `string` | A URI that points to the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.  The `value` field and `externalValue` field are mutually exclusive. See the rules for resolving [Relative References](#relativeReferencesURI).
+<a name="exampleExternalValue"></a>externalValue | `string` | A URI that identifies the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents.  The `value` field and `externalValue` field are mutually exclusive. See the rules for resolving [Relative References](#relativeReferencesURI).
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -2145,7 +2154,7 @@ For computing links, and providing instructions to execute them, a [runtime expr
 
 Field Name  |  Type  | Description
 ---|:---:|---
-<a name="linkOperationRef"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. See the rules for resolving [Relative References](#relativeReferencesURI).
+<a name="linkOperationRef"></a>operationRef | `string` | A URI identifying an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operationObject). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operationObject) in the OpenAPI definition. See the rules for resolving [Relative References](#relativeReferencesURI).
 <a name="linkOperationId"></a>operationId  | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`.  This field is mutually exclusive of the `operationRef` field.  
 <a name="linkParameters"></a>parameters   | Map[`string`, Any \| [{expression}](#runtimeExpression)] | A map representing parameters to pass to an operation as specified with `operationId` or identified via `operationRef`. The key is the parameter name to be used (optionally qualified with the parameter location, e.g. `path.id` for an `id` parameter in the path), whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.
 <a name="linkRequestBody"></a>requestBody | Any \| [{expression}](#runtimeExpression) | A literal value or [{expression}](#runtimeExpression) to use as a request body when calling the target operation.
@@ -2366,7 +2375,7 @@ description: Pets operations
 
 A simple object to allow referencing other components in the OpenAPI document, internally and externally.
 
-The `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the location of the value being referenced.
+The `$ref` string value contains a URI [RFC3986](https://tools.ietf.org/html/rfc3986), which identifies the value being referenced.
 
 See the rules for resolving [Relative References](#relativeReferencesURI).
 
@@ -2422,7 +2431,7 @@ These types can be objects, but also primitives and arrays. This object is a sup
 
 For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-bhutton-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00).
 
-Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics.
+Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics; this includes keywords such as `$schema`, `$id`, `$ref`, and `$dynamicRef` being URIs rather than URLs.
 Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.
 
 ##### Properties