diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 0fab4bd20..2b23e7fbe 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -1,15 +1,16 @@ -name: Lint +name: Lint specification markdown file on: pull_request: types: [opened, reopened, synchronize, ready_for_review] + paths: + - 'spec/asyncapi.md' jobs: lint: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Run linter - run: npx mdv spec/*.md - + run: docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:v0.35.0 "spec/asyncapi.md" \ No newline at end of file diff --git a/.github/workflows/new-spec-release.yml b/.github/workflows/new-spec-release.yml index eadf1fda3..11c59cd0b 100644 --- a/.github/workflows/new-spec-release.yml +++ b/.github/workflows/new-spec-release.yml @@ -13,12 +13,12 @@ jobs: GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} steps: - name: Checkout Current repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: path: spec ref: ${{ github.event.release.target_commitish }} - name: Checkout Another repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: asyncapi/website path: website @@ -32,7 +32,7 @@ jobs: run: | git checkout -b spec-release-${{github.event.release.tag_name}} - name: Check for previous spec file and remove it - uses: actions/github-script@v3 + uses: actions/github-script@v6 with: github-token: ${{ env.GITHUB_TOKEN }} script: | @@ -53,14 +53,14 @@ jobs: run: | cp ../spec/spec/asyncapi.md ./pages/docs/reference/specification/${{github.event.release.tag_name}}.md - name: Remove Table of Contents from Spec - uses: actions/github-script@v4 + uses: actions/github-script@v6 with: github-token: ${{ env.GITHUB_TOKEN }} script: | const script = require('./spec/.github/scripts/remove-toc'); script(`${{github.event.release.tag_name}}`); - name: Change the redirect file to point to latest spec - uses: actions/github-script@v3 + uses: actions/github-script@v6 if: ${{github.event.release.prerelease == false}} with: github-token: ${{ env.GITHUB_TOKEN }} @@ -90,7 +90,7 @@ jobs: fs.writeFileSync("./website/public/_redirects", newRedirect); - name: Remove previous pre-release redirects in case of a new release - uses: actions/github-script@v3 + uses: actions/github-script@v6 with: github-token: ${{ env.GITHUB_TOKEN }} script: | @@ -125,7 +125,7 @@ jobs: fs.writeFileSync("./website/public/_redirects", newRedirect); - name: Change the redirect file to point to specs - uses: actions/github-script@v3 + uses: actions/github-script@v6 with: github-token: ${{ env.GITHUB_TOKEN }} script: | diff --git a/.github/workflows/update-spec.yaml b/.github/workflows/update-spec.yaml index d5ad7aa1e..49b2481b2 100644 --- a/.github/workflows/update-spec.yaml +++ b/.github/workflows/update-spec.yaml @@ -15,11 +15,11 @@ jobs: GITHUB_TOKEN: ${{ secrets.GH_TOKEN }} steps: - name: Checkout Current repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: path: spec - name: Checkout Another repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 with: repository: asyncapi/website path: website @@ -43,7 +43,7 @@ jobs: run: | cp ../spec/spec/asyncapi.md ./pages/docs/reference/specification/${{ steps.latest_version.outputs.latest_tag }}.md - name: Remove Table of Contents from Spec - uses: actions/github-script@v4 + uses: actions/github-script@v6 with: github-token: ${{ env.GITHUB_TOKEN }} script: | diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 000000000..7b77ce976 --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,9 @@ +# MD013/line-length - Line length +# We should keep it disabled as this line length limit do not maeke sense really +MD013: false +# MD033/no-inline-html - Inline HTML +# We use HTML links in deadings all over the place. Probably this is why links in GitHub do not work, but that requires investingation if we can remove them really +MD033: false +# MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content +# For now hard to say how that should be fixed as we have such duplicates like Fixed Fields all over the place +MD024: false \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c82242d80..d096c5f46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -243,6 +243,14 @@ A pull request can be merged if all the following conditions are met: * There is, at least, a mininum of 3 approvals from the [repository code owners](./CODEOWNERS). * Sufficient time has passed to let all code owners review the pull request. As of now, it should be a minimum of 1 week. If all code owners have already approved a pull request, it's ok not to wait for this period of time. +## Linting specification document + +Always make sure that the specification markdown file has no markdown-related errors. + +Instead of waiting for GitHub Actions workflow to check markdown file, you can do it locally by calling the following docker command: +```bash +docker run -v $PWD:/workdir ghcr.io/igorshubovych/markdownlint-cli:v0.35.0 "spec/asyncapi.md" +``` ## References This document was adapted from the [GraphQL Specification Contribution Guide](https://github.com/graphql/graphql-spec/blob/main/CONTRIBUTING.md). \ No newline at end of file diff --git a/mlc_config.json b/mlc_config.json deleted file mode 100644 index 01833db7f..000000000 --- a/mlc_config.json +++ /dev/null @@ -1,19 +0,0 @@ -{ - "ignorePatterns": [ - { - "pattern": "^https://github.com/asyncapi/spec/tree/BRANCH_NAME" - }, - { - "pattern": "^https://github.com/asyncapi/spec-json-schemas/tree/BRANCH_NAME" - }, - { - "pattern": "^https://github.com/asyncapi/parser-js/tree/BRANCH_NAME" - }, - { - "pattern": "^https://github.com/asyncapi/website/pull/PULLREQUEST" - }, - { - "pattern": "^https://github.com/asyncapi/spec/blob/.*.md$" - } - ] -} diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 1fb6c8bd4..26bbd7f33 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -1,10 +1,10 @@ # AsyncAPI Specification -#### Disclaimer +## Disclaimer Part of this content has been taken from the great work done by the folks at the [OpenAPI Initiative](https://openapis.org). Mainly because **it's a great work** and we want to keep as much compatibility as possible with the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification). -#### Version 2.6.0 +## Version 2.6.0 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). @@ -86,29 +86,37 @@ It means that the [application](#definitionsApplication) allows [consumers](#def ## Definitions -#### Server +### Server + A server MAY be a message broker that is capable of sending and/or receiving between a [producer](#definitionsProducer) and [consumer](#definitionsConsumer). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server. -#### Application -An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). +### Application + +An application is any kind of computer program or a group of them. It MUST be a [producer](#definitionsProducer), a [consumer](#definitionsConsumer) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, etc. An application MAY be written in any number of different programming languages as long as they support the selected [protocol](#definitionsProtocol). An application MUST also use a protocol supported by the [server](#definitionsServer) in order to connect and exchange [messages](#definitionsMessage). + +### Producer -#### Producer A producer is a type of application, connected to a [server](#definitionsServer), that is creating [messages](#definitionsMessage) and addressing them to [channels](#definitionsChannel). A producer MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern. -#### Consumer +### Consumer + A consumer is a type of application, connected to a [server](#definitionsServer) via a supported [protocol](#definitionsProtocol), that is consuming [messages](#definitionsMessage) from [channels](#definitionsChannel). A consumer MAY be consuming from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. -#### Message -A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. +### Message + +A message is the mechanism by which information is exchanged via a channel between [servers](#definitionsServer) and applications. A message MUST contain a payload and MAY also contain headers. The headers MAY be subdivided into [protocol](#definitionsProtocol)-defined headers and header properties defined by the application which can act as supporting metadata. The payload contains the data, defined by the application, which MUST be serialized into a format (JSON, XML, Avro, binary, etc.). Since a message is a generic mechanism, it can support multiple interaction patterns such as event, command, request, or response. + +### Channel -#### Channel A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Producer](#definitionsProducer) applications send messages to channels and [consumer](#definitionsConsumer) applications consume messages from channels. [Servers](#definitionsServer) MAY support many channel instances, allowing messages with different content to be addressed to different channels. Depending on the [server](#definitionsServer) implementation, the channel MAY be included in the message via protocol-defined headers. -#### Protocol +### Protocol + A protocol is the mechanism (wireline protocol or API) by which [messages](#definitionsMessage) are exchanged between the application and the [channel](#definitionsChannel). Example protocols include, but are not limited to, AMQP, HTTP, JMS, Kafka, Anypoint MQ, MQTT, Solace, STOMP, Mercure, WebSocket, Google Pub/Sub, Pulsar. -#### Bindings -A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. +### Bindings + +A "binding" (or "protocol binding") is a mechanism to define protocol-specific information. Therefore, a protocol binding MUST define protocol-specific information only. ## Specification @@ -170,7 +178,6 @@ Field Name | Type | Description 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 MAY be extended with [Specification Extensions](#specificationExtensions). #### AsyncAPI Version String @@ -189,7 +196,7 @@ This field represents a unique universal identifier of the [application](#defini It is RECOMMENDED to use a [URN](https://tools.ietf.org/html/rfc8141) to globally and uniquely identify the application during long periods of time, even after it becomes unavailable or ceases to exist. -###### Examples +##### Examples ```json { @@ -229,7 +236,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -##### Info Object Example: +##### Info Object Example ```json { @@ -277,7 +284,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -##### Contact Object Example: +##### Contact Object Example ```json { @@ -306,7 +313,7 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). -##### License Object Example: +##### License Object Example ```json { @@ -351,7 +358,6 @@ production: protocolVersion: '1.0.0' ``` - #### Server Object An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. @@ -515,7 +521,6 @@ servers: default: v2 ``` - #### Server Variable Object An object representing a Server Variable for server URL template substitution. @@ -531,10 +536,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). - - - - #### Default Content Type A string representing the default content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`). This value MUST be used by schema parsers when the [contentType](#messageObjectContentType) property is omitted. @@ -553,11 +554,6 @@ In case a message can't be encoded/decoded using this value, schema parsers MUST defaultContentType: application/json ``` - - - - - #### Channels Object Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers. @@ -591,9 +587,6 @@ user/signedup: $ref: "#/components/messages/userSignedUp" ``` - - - #### Channel Item Object Describes the operations available on a single channel. @@ -602,7 +595,7 @@ Describes the operations available on a single channel. Field Name | Type | Description ---|:---:|--- -$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. +$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. @@ -688,7 +681,6 @@ subscribe: - $ref: '#/components/messages/login' ``` - Using explicit by-name references to the servers on which the channel is available: ```json @@ -724,10 +716,6 @@ bindings: is: queue ``` - - - - #### Operation Object Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. @@ -836,9 +824,6 @@ traits: - $ref: "#/components/operationTraits/kafka" ``` - - - #### Operation Trait Object Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except `message` and `traits`. @@ -877,9 +862,6 @@ bindings: ack: false ``` - - - #### Parameters Object Describes a map of parameters included in a channel name. @@ -926,10 +908,6 @@ user/{userId}/signup: $ref: "#/components/messages/userSignedUp" ``` - - - - #### Parameter Object Describes a parameter included in a channel name. @@ -980,9 +958,6 @@ user/{userId}/signup: $ref: "#/components/messages/userSignedUp" ``` - - - #### Server Bindings Object Map describing protocol-specific definitions for a server. @@ -1013,8 +988,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). - - #### Channel Bindings Object Map describing protocol-specific definitions for a channel. @@ -1045,8 +1018,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). - - #### Operation Bindings Object Map describing protocol-specific definitions for an operation. @@ -1077,9 +1048,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). - - - #### Message Bindings Object Map describing protocol-specific definitions for a message. @@ -1110,12 +1078,6 @@ Field Name | Type | Description This object MAY be extended with [Specification Extensions](#specificationExtensions). - - - - - - #### Message Object Describes a message received on a given channel and operation. @@ -1149,17 +1111,16 @@ The following table contains a set of values that every implementation MUST supp Name | Allowed values | Notes ---|:---:|--- [AsyncAPI 2.6.0 Schema Object](#schemaObject) | `application/vnd.aai.asyncapi;version=2.6.0`, `application/vnd.aai.asyncapi+json;version=2.6.0`, `application/vnd.aai.asyncapi+yaml;version=2.6.0` | This is the default when a `schemaFormat` is not provided. -[JSON Schema Draft 07](https://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | +[JSON Schema Draft 07](https://json-schema.org/specification-links.html#draft-7) | `application/schema+json;version=draft-07`, `application/schema+yaml;version=draft-07` | The following table contains a set of values that every implementation is RECOMMENDED to support. Name | Allowed values | Notes ---|:---:|--- [Avro 1.9.0 schema](https://avro.apache.org/docs/1.9.0/spec.html#schemas) | `application/vnd.apache.avro;version=1.9.0`, `application/vnd.apache.avro+json;version=1.9.0`, `application/vnd.apache.avro+yaml;version=1.9.0` | -[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | +[OpenAPI 3.0.0 Schema Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject) | `application/vnd.oai.openapi;version=3.0.0`, `application/vnd.oai.openapi+json;version=3.0.0`, `application/vnd.oai.openapi+yaml;version=3.0.0` | [RAML 1.0 data type](https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/) | `application/raml+yaml;version=1.0` | - ##### Message Object Example ```json @@ -1308,12 +1269,6 @@ payload: $ref: 'path/to/user-create.avsc/#UserCreate' ``` - - - - - - #### Message Trait Object Describes a trait that MAY be applied to a [Message Object](#messageObject). This object MAY contain any property from the [Message Object](#messageObject), except `payload` and `traits`. @@ -1356,13 +1311,13 @@ contentType: application/json #### Message Example Object -Message Example Object represents an example of a [Message Object](#messageObject) and MUST contain either **headers** and/or **payload** fields. +Message Example Object represents an example of a [Message Object](#messageObject) and MUST contain either **headers** and/or **payload** fields. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -headers | `Map[string, any]` | The value of this field MUST validate against the [Message Object's headers](#messageObjectHeaders) field. +headers | `Map[string, any]` | The value of this field MUST validate against the [Message Object's headers](#messageObjectHeaders) field. payload | `any` | The value of this field MUST validate against the [Message Object's payload](#messageObjectPayload) field. name | `string` | A machine-friendly name. summary | `string` | A short summary of what the example is about. @@ -1412,6 +1367,7 @@ A Tags object is a list of Tag Objects. Allows adding meta data to a single tag. ##### Fixed Fields + Field Name | Type | Description ---|:---:|--- name | `string` | **REQUIRED.** The name of the tag. @@ -1424,8 +1380,8 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { - "name": "user", - "description": "User-related messages" + "name": "user", + "description": "User-related messages" } ``` @@ -1434,12 +1390,6 @@ name: user description: User-related messages ``` - - - - - - #### External Documentation Object Allows referencing an external resource for extended documentation. @@ -1476,6 +1426,7 @@ The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/ For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification. ##### Fixed Fields + Field Name | Type | Description ---|:---:|--- $ref | `string` | **REQUIRED.** The reference string. @@ -1502,10 +1453,10 @@ All objects defined within the components object will have no effect on the API ##### Fixed Fields Field Name | Type | Description ----|:---|--- +---|:---|--- schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). - serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). + serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). channels | Map[`string`, [Channel Item Object](#channelItemObject)] | An object to hold reusable [Channel Item Objects](#channelItemObject). messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject). securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). @@ -1524,7 +1475,7 @@ All the fixed fields declared above are objects that MUST use keys that match th Field Name Examples: -``` +```plaintext User User_1 User_Name @@ -1805,6 +1756,7 @@ Alternatively, any time a Schema Object can be used, a [Reference Object](#refer In addition to the JSON Schema fields, the following AsyncAPI vocabulary fields MAY be used for further schema documentation: ##### Fixed Fields + Field Name | Type | Description ---|:---:|--- discriminator | `string` | Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. The property name used MUST be defined at this schema and it MUST be in the `required` property list. When used, the value MUST be the name of this schema or any schema that inherits it. See [Composition and Inheritance](#schemaComposition) for more details. @@ -1816,7 +1768,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ###### Composition and Inheritance (Polymorphism) The AsyncAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition. -`allOf` takes in an array of object definitions that are validated *independently* but together compose a single object. +`allOf` takes in an array of object definitions that are validated _independently_ but together compose a single object. While composition offers model extensibility, it does not imply a hierarchy between the models. To support polymorphism, AsyncAPI Specification adds the support of the `discriminator` field. @@ -1827,7 +1779,7 @@ There are two ways to define the value of a discriminator for an inheriting inst - Use the schema's name. - Override the schema's name by overriding the property with a new value. If exists, this takes precedence over the schema's name. -As such, inline schema definitions, which do not have a given id, *cannot* be used in polymorphism. +As such, inline schema definitions, which do not have a given id, _cannot_ be used in polymorphism. ##### Schema Object Examples @@ -2212,25 +2164,22 @@ schemas: - color ``` - - - - #### Security Scheme Object Defines a security scheme that can be used by the operations. Supported schemes are: -* User/Password. -* API key (either as user or as password). -* X.509 certificate. -* End-to-end encryption (either symmetric or asymmetric). -* HTTP authentication. -* HTTP API key. -* OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). -* [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). -* SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). +- User/Password. +- API key (either as user or as password). +- X.509 certificate. +- End-to-end encryption (either symmetric or asymmetric). +- HTTP authentication. +- HTTP API key. +- OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749). +- [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). +- SASL (Simple Authentication and Security Layer) as defined in [RFC4422](https://tools.ietf.org/html/rfc4422). ##### Fixed Fields + Field Name | Type | Applies To | Description ---|:---:|---|--- type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"userPassword"`, `"apiKey"`, `"X509"`, `"symmetricEncryption"`, `"asymmetricEncryption"`, `"httpApiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`, `"plain"`, `"scramSha256"`, `"scramSha512"`, and `"gssapi"`. @@ -2386,6 +2335,7 @@ type: scramSha512 Allows configuration of the supported OAuth Flows. ##### Fixed Fields + Field Name | Type | Description ---|:---:|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow. @@ -2400,6 +2350,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens 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 an absolute URL. @@ -2508,11 +2459,11 @@ petstore_auth: ### Correlation ID Object -An object that specifies an identifier at design time that can used for message tracing and correlation. +An object that specifies an identifier at design time that can used for message tracing and correlation. For specifying and computing the location of a Correlation ID, a [runtime expression](#runtimeExpression) is used. -##### Fixed Fields +#### Fixed Fields Field Name | Type | Description ---|:---|--- @@ -2521,7 +2472,7 @@ location | `string` | **REQUIRED.** A [runtime expression](#runtimeExpression) t This object MAY be extended with [Specification Extensions](#specificationExtensions). -##### Examples +#### Examples ```json { @@ -2542,7 +2493,7 @@ This mechanism is used by [Correlation ID Object](#correlationIdObject). The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax: -``` +```plaintext expression = ( "$message" "." source ) source = ( header-reference | payload-reference ) header-reference = "header" ["#" fragment] @@ -2552,7 +2503,7 @@ The runtime expression is defined by the following [ABNF](https://tools.ietf.org The table below provides examples of runtime expressions and examples of their use in a value: -##### Examples +#### Examples Source Location | Example expression | Notes ---|:---|:---| @@ -2584,7 +2535,6 @@ Tools that do not recognize a specific `format` MAY default back to the `type` a The formats defined by the AsyncAPI Specification are: - Common Name | `type` | [`format`](#dataTypeFormat) | Comments ----------- | ------ | -------- | -------- integer | `integer` | `int32` | signed 32 bits