From cc050bfa9cab892799cdca0aaccddf1b78c7b435 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Wed, 4 May 2022 18:00:08 +0200 Subject: [PATCH 1/2] docs(spec): clarify how URL form is resolved Refs #674 --- spec/asyncapi.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index a0ed1599a..842903938 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -42,9 +42,10 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Channel](#definitionsChannel) - [Protocol](#definitionsProtocol) - [Specification](#specification) - - [Format](#format) - - [File Structure](#file-structure) - - [Schema](#schema) + - [Format](#format) + - [File Structure](#file-structure) + - [Relative References In URLs](#relativeReferencesURL) + - [Schema](#schema) - [AsyncAPI Object](#A2SObject) - [AsyncAPI Version String](#A2SVersionString) - [Identifier](#A2SIdString) @@ -144,6 +145,11 @@ connected parts at the discretion of the author. In the latter case, [Reference By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. +### Relative References in 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. + ### Schema #### AsyncAPI Object @@ -218,7 +224,7 @@ Field Name | Type | Description title | `string` | **Required.** The title of the application. version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version). description | `string` | A short description of the application. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL. +termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of a URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. @@ -267,7 +273,7 @@ Contact information for the exposed API. Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. MUST be in the format of a URL. +url | `string` | The URL pointing to the contact information. This MUST be in the form of a URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -297,7 +303,7 @@ License information for the exposed API. Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The license name used for the API. -url | `string` | A URL to the license used for the API. MUST be in the format of a URL. +url | `string` | A URL to the license used for the API. This MUST be in the form of a URL. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1407,7 +1413,7 @@ Allows referencing an external resource for extended documentation. Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -url | `string` | **Required.** The URL for the target documentation. Value MUST be in the format of a URL. +url | `string` | **Required.** The URL for the target documentation. This MUST be in the form of a URL. This object can be extended with [Specification Extensions](#specificationExtensions). From 013f4bdfb6a3549472e50f39c506ee1f902738e4 Mon Sep 17 00:00:00 2001 From: Vladimir Gorej Date: Tue, 5 Jul 2022 13:28:26 +0200 Subject: [PATCH 2/2] docs: allow no relative references in URLs --- spec/asyncapi.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 842903938..9fa751125 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -44,7 +44,7 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Specification](#specification) - [Format](#format) - [File Structure](#file-structure) - - [Relative References In URLs](#relativeReferencesURL) + - [Absolute URLs](#absolute-urls) - [Schema](#schema) - [AsyncAPI Object](#A2SObject) - [AsyncAPI Version String](#A2SVersionString) @@ -145,10 +145,9 @@ connected parts at the discretion of the author. In the latter case, [Reference By convention, the AsyncAPI Specification (A2S) file is named `asyncapi.json` or `asyncapi.yaml`. -### Relative References in URLs +### Absolute 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. +Unless specified otherwise, all properties that are absolute URLs are defined by [RFC3986, section 4.3](https://datatracker.ietf.org/doc/html/rfc3986#section-4.3). ### Schema @@ -224,7 +223,7 @@ Field Name | Type | Description title | `string` | **Required.** The title of the application. version | `string` | **Required** Provides the version of the application API (not to be confused with the specification version). description | `string` | A short description of the application. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of a URL. +termsOfService | `string` | A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL. contact | [Contact Object](#contactObject) | The contact information for the exposed API. license | [License Object](#licenseObject) | The license information for the exposed API. @@ -273,7 +272,7 @@ Contact information for the exposed API. Field Name | Type | Description ---|:---:|--- name | `string` | The identifying name of the contact person/organization. -url | `string` | The URL pointing to the contact information. This MUST be in the form of a URL. +url | `string` | The URL pointing to the contact information. This MUST be in the form of an absolute URL. email | `string` | The email address of the contact person/organization. MUST be in the format of an email address. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -303,7 +302,7 @@ License information for the exposed API. Field Name | Type | Description ---|:---:|--- name | `string` | **Required.** The license name used for the API. -url | `string` | A URL to the license used for the API. This MUST be in the form of a URL. +url | `string` | A URL to the license used for the API. This MUST be in the form of an absolute URL. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -1413,7 +1412,7 @@ Allows referencing an external resource for extended documentation. Field Name | Type | Description ---|:---:|--- description | `string` | A short description of the target documentation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. -url | `string` | **Required.** The URL for the target documentation. This MUST be in the form of a URL. +url | `string` | **Required.** The URL for the target documentation. This MUST be in the form of an absolute URL. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -2202,7 +2201,7 @@ Field Name | Type | Applies To | Description scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **REQUIRED**. An object containing configuration information for the flow types supported. -openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. +openIdConnectUrl | `string` | `openIdConnect` | **REQUIRED**. OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of an absolute URL. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -2364,9 +2363,9 @@ Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Applies To | Description ---|:---:|---|--- -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. +authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of an absolute URL. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of an absolute URL. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL. scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. This object MAY be extended with [Specification Extensions](#specificationExtensions).