diff --git a/.github/ISSUE_TEMPLATE/release.md b/.github/ISSUE_TEMPLATE/release.md index f221a18b8..5677b2727 100644 --- a/.github/ISSUE_TEMPLATE/release.md +++ b/.github/ISSUE_TEMPLATE/release.md @@ -22,6 +22,20 @@ Release X.X.X is scheduled for XXXX ### Release notes: * draft PR - https://github.com/asyncapi/website/pull/PULLREQUEST +### Potential work to be included in this version + +#### Accepted + +- [ ] + +#### Pending + +- [ ] + +#### Discarded + +- [ ] + ### Progress: - [ ] Create release branches - [ ] spec @@ -59,3 +73,7 @@ Release X.X.X is scheduled for XXXX - [ ] spec-json-schemas - [ ] parser-js - [ ] Update RELEASE_PROCESS doc with any changes + +### Cleanup tasks after the release + +- [ ] diff --git a/.github/workflows/link-check-cron.yml b/.github/workflows/link-check-cron.yml index 44e1a5cb0..2d1e1fc02 100644 --- a/.github/workflows/link-check-cron.yml +++ b/.github/workflows/link-check-cron.yml @@ -34,4 +34,4 @@ jobs: fields: repo,action,workflow env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_CI_FAIL_NOTIFY }} - if: failure() # Only, on failure, send a message on the Slack Docs Channel (if there are broken links) + if: failure() # Only, on failure, send a message on the 94_bot-failing-ci slack channel diff --git a/.github/workflows/stale-issues-prs.yml b/.github/workflows/stale-issues-prs.yml index c1c0c61da..5dc053a49 100644 --- a/.github/workflows/stale-issues-prs.yml +++ b/.github/workflows/stale-issues-prs.yml @@ -13,7 +13,7 @@ jobs: name: Mark issue or PR as stale runs-on: ubuntu-latest steps: - - uses: actions/stale@v4.0.0 + - uses: actions/stale@v5.1.0 with: repo-token: ${{ secrets.GITHUB_TOKEN }} stale-issue-message: | @@ -41,4 +41,5 @@ jobs: stale-issue-label: stale stale-pr-label: stale exempt-issue-labels: keep-open - exempt-pr-labels: keep-open \ No newline at end of file + exempt-pr-labels: keep-open + close-issue-reason: not_planned diff --git a/LICENSE b/LICENSE index 23b34fdff..7a4a3ea24 100644 --- a/LICENSE +++ b/LICENSE @@ -1,3 +1,4 @@ + Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ @@ -178,7 +179,7 @@ APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "{}" + boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a @@ -186,7 +187,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright The Linux Foundation + Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -198,4 +199,4 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and - limitations under the License. + limitations under the License. \ No newline at end of file diff --git a/NOTICE b/NOTICE new file mode 100644 index 000000000..3003c18d6 --- /dev/null +++ b/NOTICE @@ -0,0 +1,2 @@ +AsyncAPI Initiative +Copyright The Linux Foundation \ No newline at end of file diff --git a/README.md b/README.md index 2de11dbb9..c3079baa5 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ ## Read the specification The latest draft specification can be found at [spec/asyncapi.md](./spec/asyncapi.md) which tracks the latest commit to the master branch in this repository. +The human-readable markdown file is the source of truth for the specification. - [Version 2.5.0](https://github.com/asyncapi/spec/blob/v2.5.0/spec/asyncapi.md) (latest) - [Version 2.4.0](https://github.com/asyncapi/spec/blob/v2.4.0/spec/asyncapi.md) diff --git a/examples/streetlights-kafka.yml b/examples/streetlights-kafka.yml index 22119954d..9ce3c60c9 100644 --- a/examples/streetlights-kafka.yml +++ b/examples/streetlights-kafka.yml @@ -15,12 +15,18 @@ info: url: https://www.apache.org/licenses/LICENSE-2.0 servers: - test: - url: test.mykafkacluster.org:8092 + scram-connections: + url: test.mykafkacluster.org:18092 protocol: kafka-secure - description: Test broker - security: - - saslScram: [] + description: Test broker secured with scramSha256 + security: + - saslScram: [] + mtls-connections: + url: test.mykafkacluster.org:28092 + protocol: kafka-secure + description: Test broker secured with X509 + security: + - certs: [] defaultContentType: application/json @@ -139,6 +145,9 @@ components: saslScram: type: scramSha256 description: Provide your username and password for SASL/SCRAM authentication + certs: + type: X509 + description: Download the certificate files from service provider parameters: streetlightId: diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 822cba5d3..da28e712f 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) + - [Absolute URLs](#absolute-urls) + - [Schema](#schema) - [AsyncAPI Object](#A2SObject) - [AsyncAPI Version String](#A2SVersionString) - [Identifier](#A2SIdString) @@ -144,6 +145,10 @@ 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`. +### Absolute URLs + +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 #### AsyncAPI Object @@ -155,18 +160,18 @@ It combines resource listing and API declaration together into one document. Field Name | Type | Description ---|:---:|--- -asyncapi | [AsyncAPI Version String](#A2SVersionString) | **Required.** Specifies the AsyncAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (1.0.*). Patch versions will correspond to patches of this document. +asyncapi | [AsyncAPI Version String](#A2SVersionString) | **REQUIRED.** Specifies the AsyncAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (1.0.*). Patch versions will correspond to patches of this document. id | [Identifier](#A2SIdString) | Identifier of the [application](#definitionsApplication) the AsyncAPI document is defining. -info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. +info | [Info Object](#infoObject) | **REQUIRED.** Provides metadata about the API. The metadata can be used by the clients if needed. servers | [Servers Object](#serversObject) | Provides connection details of servers. defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. -channels | [Channels Object](#channelsObject) | **Required** The available channels and messages for the API. +channels | [Channels Object](#channelsObject) | **REQUIRED** The available channels and messages for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). #### AsyncAPI Version String @@ -215,14 +220,14 @@ The metadata can be used by the clients if needed. 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). +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 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. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Info Object Example: @@ -267,10 +272,10 @@ 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 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). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Contact Object Example: @@ -296,10 +301,10 @@ 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. +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 an absolute URL. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### License Object Example: @@ -569,7 +574,7 @@ Describes the operations available on a single channel. Field Name | Type | Description ---|:---:|--- -$ref | `string` | Allows for an external definition of this channel item. The referenced structure MUST be in the format of a [Channel Item Object](#channelItemObject). If there are conflicts between the referenced definition and this Channel Item's definition, the behavior is *undefined*.

**Deprecated:** Usage of the `$ref` property has been deprecated. +$ref | `string` | Allows for a referenced definition of this channel item. The referenced structure MUST be in the form of a [Channel Item Object](#channelItemObject). In case a Channel Item Object field appears both in the defined object and the referenced object, the behavior is *undefined*. Resolution is done as defined by the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).

**Deprecated:** Usage of the `$ref` property has been deprecated. description | `string` | An optional description of this channel item. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. servers | [`string`] | The servers on which this channel is available, specified as an optional unordered list of names (string keys) of [Server Objects](#serverObject) defined in the [Servers Object](#serversObject) (a map). If `servers` is absent or empty then this channel must be available on all servers defined in the [Servers Object](#serversObject). subscribe | [Operation Object](#operationObject) | A definition of the SUBSCRIBE operation, which defines the messages produced by the application and sent to the channel. @@ -577,7 +582,7 @@ Field Name | Type | Description parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel name. It SHOULD be present only when using channels with expressions (as defined by [RFC 6570 section 2.2](https://tools.ietf.org/html/rfc6570#section-2.2)). bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Channel Item Object Example @@ -715,7 +720,7 @@ Field Name | Type | Description traits | [[Operation Trait Object](#operationTraitObject) | [Reference Object](#referenceObject) ] | A list of traits to apply to the operation object. Traits MUST be merged into the operation object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. message | [Message Object](#messageObject) | [Reference Object](#referenceObject) | Map["oneOf", [[Message Object](#messageObject) | [Reference Object](#referenceObject)]] | A definition of the message that will be published or received by this operation. Map containing a single `oneOf` key is allowed here to specify multiple messages. However, **a message MUST be valid only against one of the message objects.** -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Object Example @@ -824,7 +829,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation. bindings | [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Operation Trait Object Example @@ -909,7 +914,7 @@ Field Name | Type | Description schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | Definition of the parameter. location | `string` | A [runtime expression](#runtimeExpression) that specifies the location of the parameter value. Even when a definition for the target field exists, it MUST NOT be used to validate this parameter but, instead, the `schema` property MUST be used. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Parameter Object Example @@ -976,7 +981,7 @@ Field Name | Type | Description `mercure` | [Mercure Server Binding](https://github.com/asyncapi/bindings/blob/master/mercure#server) | Protocol-specific information for a Mercure server. `ibmmq` | [IBM MQ Server Binding](https://github.com/asyncapi/bindings/blob/master/ibmmq#server-binding-object) | Protocol-specific information for an IBM MQ server. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1006,7 +1011,7 @@ Field Name | Type | Description `mercure` | [Mercure Channel Binding](https://github.com/asyncapi/bindings/blob/master/mercure#channel) | Protocol-specific information for a Mercure channel. `ibmmq` | [IBM MQ Channel Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#channel-binding-object) | Protocol-specific information for an IBM MQ channel. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1035,7 +1040,7 @@ Field Name | Type | Description `redis` | [Redis Operation Binding](https://github.com/asyncapi/bindings/blob/master/redis#operation) | Protocol-specific information for a Redis operation. `mercure` | [Mercure Operation Binding](https://github.com/asyncapi/bindings/blob/master/mercure#operation) | Protocol-specific information for a Mercure operation. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1066,7 +1071,7 @@ Field Name | Type | Description `mercure` | [Mercure Message Binding](https://github.com/asyncapi/bindings/blob/master/mercure#message) | Protocol-specific information for a Mercure message. `ibmmq` | [IBM MQ Message Binding](https://github.com/asyncapi/bindings/tree/master/ibmmq#message-binding-object) | Protocol-specific information for an IBM MQ message. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -1098,7 +1103,7 @@ Field Name | Type | Description examples | [[Message Example Object](#messageExampleObject)] | List of examples. traits | [[Message Trait Object](#messageTraitObject) | [Reference Object](#referenceObject)] | A list of traits to apply to the message object. Traits MUST be merged into the message object using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm in the same order they are defined here. The resulting object MUST be a valid [Message Object](#messageObject). -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Schema formats table @@ -1296,7 +1301,7 @@ Field Name | Type | Description bindings | [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message. examples | [[Message Example Object](#messageExampleObject)] | List of examples. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Message Trait Object Example @@ -1325,7 +1330,7 @@ Field Name | Type | Description name | `string` | A machine-friendly name. summary | `string` | A short summary of what the example is about. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Message Example Object Example @@ -1372,11 +1377,11 @@ Allows adding meta data to a single tag. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -name | `string` | **Required.** The name of the tag. +name | `string` | **REQUIRED.** The name of the tag. description | `string` | A short description for the tag. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Tag Object Example @@ -1407,9 +1412,9 @@ 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 an absolute URL. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### External Documentation Object Example @@ -1436,7 +1441,7 @@ For this specification, reference resolution is done as defined by the JSON Refe ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -$ref | `string` | **Required.** The reference string. +$ref | `string` | **REQUIRED.** The reference string. This object cannot be extended with additional properties and any properties added SHALL be ignored. @@ -1476,7 +1481,7 @@ Field Name | Type | Description operationBindings | Map[`string`, [Operation Bindings Object](#operationBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Bindings Objects](#operationBindingsObject). messageBindings | Map[`string`, [Message Bindings Object](#messageBindingsObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Bindings Objects](#messageBindingsObject). -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). All the fixed fields declared above are objects that MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`. @@ -1769,7 +1774,7 @@ Field Name | Type | Description externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ###### Composition and Inheritance (Polymorphism) @@ -2198,7 +2203,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). @@ -2346,8 +2351,8 @@ Allows configuration of the supported OAuth Flows. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow -password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Protected Credentials flow +implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow. +password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Protected Credentials flow. clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. @@ -2360,9 +2365,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). @@ -2477,7 +2482,7 @@ Field Name | Type | Description description | `string` | An optional description of the identifier. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. location | `string` | **REQUIRED.** A [runtime expression](#runtimeExpression) that specifies the location of the correlation ID. -This object can be extended with [Specification Extensions](#specificationExtensions). +This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### Examples