From b46420f08ac077218476bdb639cddb4a005298fa Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Thu, 22 Sep 2022 16:56:48 +0200 Subject: [PATCH 01/10] feat: move operations to its own root object --- spec/asyncapi.md | 120 +++++++++++++++++++++++++++++------------------ 1 file changed, 74 insertions(+), 46 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index c6ee26101..088ff56ed 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -703,19 +703,77 @@ userCompletedOrder: +#### Operations Object +Holds a dictionary with all the [operations](#operation-object) this application MUST implement. -#### Operation Object +Note: If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#componentsOperations). + +##### Patterned Fields + +Field Pattern | Type | Description +---|:---:|--- +{operationId} | [Operation Object](#channelItemObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. -Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received. +##### Operations Object Example + +```json +{ + "onUserSignUp": { + "summary": "Action to sign a user up.", + "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", + "tags": [ + { "name": "user" }, + { "name": "signup" }, + { "name": "register" } + ], + "bindings": { + "amqp": { + "ack": false + } + }, + "traits": [ + { "$ref": "#/components/operationTraits/kafka" } + ] + } +} +``` + +```yaml +onUserSignUp: + summary: Action to sign a user up. + description: A longer description + channel: + $ref: '#/channels/userSignup' + action: send + tags: + - name: user + - name: signup + - name: register + bindings: + amqp: + ack: false + traits: + - $ref: '#/components/operationTraits/kafka' +``` + + + + +#### Operation Object -For example, an operation might describe a chat application use case where a user sends a text message to a group. A publish operation describes messages that are received by the chat application, whereas a subscribe operation describes messages that are sent by the chat application. +Describes a `send` or a `receive` operation. ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. +action | `string` | **Required**. Allowed values are `send` and `receive`. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). +channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelItemObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. @@ -723,7 +781,6 @@ 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. 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 MAY be extended with [Specification Extensions](#specificationExtensions). @@ -731,9 +788,12 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ```json { - "operationId": "registerUser", "summary": "Action to sign a user up.", "description": "A longer description", + "channel": { + "$ref": "#/channels/userSignup" + }, + "action": "send", "security": [ { "petstore_auth": [ @@ -747,28 +807,6 @@ This object MAY be extended with [Specification Extensions](#specificationExtens { "name": "signup" }, { "name": "register" } ], - "message": { - "headers": { - "type": "object", - "properties": { - "applicationInstanceId": { - "description": "Unique identifier for a given instance of the publishing application", - "type": "string" - } - } - }, - "payload": { - "type": "object", - "properties": { - "user": { - "$ref": "#/components/schemas/userCreate" - }, - "signup": { - "$ref": "#/components/schemas/signup" - } - } - } - }, "bindings": { "amqp": { "ack": false @@ -781,9 +819,11 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ``` ```yaml -operationId: registerUser summary: Action to sign a user up. description: A longer description +channel: + $ref: '#/channels/userSignup' +action: send security: - petstore_auth: - write:pets @@ -792,20 +832,6 @@ tags: - name: user - name: signup - name: register -message: - headers: - type: object - properties: - applicationInstanceId: - description: Unique identifier for a given instance of the publishing application - type: string - payload: - type: object - properties: - user: - $ref: "#/components/schemas/userCreate" - signup: - $ref: "#/components/schemas/signup" bindings: amqp: ack: false @@ -818,7 +844,7 @@ traits: #### 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`. +Describes a trait that MAY be applied to an [Operation Object](#operationObject). This object MAY contain any property from the [Operation Object](#operationObject), except the `message` and `traits` ones. If you're looking to apply traits to a message, see the [Message Trait Object](#messageTraitObject). @@ -826,7 +852,8 @@ If you're looking to apply traits to a message, see the [Message Trait Object](# Field Name | Type | Description ---|:---:|--- -operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is **case-sensitive**. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. +action | `string` | Allowed values are `send` and `receive`. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). +channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelItemObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. @@ -1473,8 +1500,9 @@ 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). channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject). - serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). + operations | Map[`string`, [Operation Item Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Item Objects](#operationObject). 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). parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject). From f115ea19805770f0de93c8dbdd398c9193cb8f79 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Mon, 13 Jun 2022 18:00:30 +0200 Subject: [PATCH 02/10] fix link to operation object --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 088ff56ed..382c6d503 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -705,7 +705,7 @@ userCompletedOrder: #### Operations Object -Holds a dictionary with all the [operations](#operation-object) this application MUST implement. +Holds a dictionary with all the [operations](#operationObject) this application MUST implement. Note: If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#componentsOperations). From b54459b9a84e3953561cc7fa58152738ed23a953 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Thu, 22 Sep 2022 16:59:01 +0200 Subject: [PATCH 03/10] Add operations to asyncapi object and ToC --- spec/asyncapi.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 382c6d503..cf9f98012 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -58,6 +58,7 @@ It means that the [application](#definitionsApplication) allows [consumers](#def - [Default Content Type](#defaultContentTypeString) - [Channels Object](#channelsObject) - [Channel Object](#channelObject) + - [Operations Object](#operationsObject) - [Operation Object](#operationObject) - [Operation Trait Object](#operationTraitObject) - [Message Object](#messageObject) @@ -168,6 +169,7 @@ Field Name | Type | Description 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) | The channels used by this [application](#definitionsApplication). +operations | [Operations Object](#operationsObject) | The operations this [application](#definitionApplication) will perform. components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). 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. From a06ff037f27a012099858a648e525d1d0993800d Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Thu, 22 Sep 2022 17:00:58 +0200 Subject: [PATCH 04/10] Fix wording of operations --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index cf9f98012..3734fe746 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -169,7 +169,7 @@ Field Name | Type | Description 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) | The channels used by this [application](#definitionsApplication). -operations | [Operations Object](#operationsObject) | The operations this [application](#definitionApplication) will perform. +operations | [Operations Object](#operationsObject) | The operations this [application](#definitionApplication) MUST implement. components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). 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. From 3d65c4bf2cfb1d7fba0addbb1f68560b5ce32224 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Fri, 9 Sep 2022 14:42:34 +0200 Subject: [PATCH 05/10] Modify operation definition --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 3734fe746..83990a20b 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -768,7 +768,7 @@ onUserSignUp: #### Operation Object -Describes a `send` or a `receive` operation. +Describes a specific operation. ##### Fixed Fields From 7cceba4eb2298671922c7c5dd76f94a1f81aea0d Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Thu, 22 Sep 2022 17:03:07 +0200 Subject: [PATCH 06/10] Fix definitionsApplication link --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 83990a20b..4ffd8484e 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -169,7 +169,7 @@ Field Name | Type | Description 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) | The channels used by this [application](#definitionsApplication). -operations | [Operations Object](#operationsObject) | The operations this [application](#definitionApplication) MUST implement. +operations | [Operations Object](#operationsObject) | The operations this [application](#definitionsApplication) MUST implement. components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). 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. From ed48ac8c577c4c4effa20eaca303f36507965217 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Mon, 12 Sep 2022 23:26:53 +0200 Subject: [PATCH 07/10] Add notice in the beginning of the spec to alert it is not yet ready --- spec/asyncapi.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 4ffd8484e..19fa74c96 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -1,3 +1,7 @@ +# ATTENTION: Work in progress + +This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to https://github.com/asyncapi/spec/issues/691. + # AsyncAPI Specification #### Disclaimer From 5185ec932c66bd2e13b1015d88b5fb7d4afc9add Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Mon, 12 Sep 2022 22:56:16 +0200 Subject: [PATCH 08/10] Replace "Note:" with markdown quote Co-authored-by: Lukasz Gornicki --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 19fa74c96..6bc9e688a 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -713,7 +713,7 @@ userCompletedOrder: Holds a dictionary with all the [operations](#operationObject) this application MUST implement. -Note: If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#componentsOperations). +> If you're looking for a place to define operations that MAY or MAY NOT be implemented by the application, consider defining them in [`components/operations`](#componentsOperations). ##### Patterned Fields From 6955484c671eeb1d6e45576fbfdb985f296be7a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=20M=C3=A9ndez?= Date: Tue, 13 Sep 2022 22:22:19 +0200 Subject: [PATCH 09/10] Update spec/asyncapi.md Co-authored-by: Lukasz Gornicki --- spec/asyncapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index 6bc9e688a..c7ed89d68 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -1,6 +1,6 @@ # ATTENTION: Work in progress -This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to https://github.com/asyncapi/spec/issues/691. +This version is not yet ready to be used. We're currently working on it. If you want to join the effort and participate in the development of the next major version of AsyncAPI, head over to [GitHub Issue that we use for tracking 3.0 development progress](https://github.com/asyncapi/spec/issues/691). # AsyncAPI Specification From 9bacca42fabd68b5cee4afcf6051b229b0ff4c06 Mon Sep 17 00:00:00 2001 From: Fran Mendez Date: Thu, 22 Sep 2022 17:04:50 +0200 Subject: [PATCH 10/10] Fix channel item links --- spec/asyncapi.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/asyncapi.md b/spec/asyncapi.md index c7ed89d68..2e44f296c 100644 --- a/spec/asyncapi.md +++ b/spec/asyncapi.md @@ -719,7 +719,7 @@ Holds a dictionary with all the [operations](#operationObject) this application Field Pattern | Type | Description ---|:---:|--- -{operationId} | [Operation Object](#channelItemObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. +{operationId} | [Operation Object](#channelObject) \| [Reference Object](#referenceObject) | The operation this application MUST implement. The field name (`operationId`) MUST be a string used to identify the operation in the document where it is defined, and its value is **case-sensitive**. Tools and libraries MAY use the `operationId` to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. ##### Operations Object Example @@ -779,7 +779,7 @@ Describes a specific operation. Field Name | Type | Description ---|:---:|--- action | `string` | **Required**. Allowed values are `send` and `receive`. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). -channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelItemObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +channel | [Reference Object](#referenceObject) | **Required**. A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation. security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied. @@ -859,7 +859,7 @@ If you're looking to apply traits to a message, see the [Message Trait Object](# Field Name | Type | Description ---|:---:|--- action | `string` | Allowed values are `send` and `receive`. Use `send` when it's expected that the application will send a message to the given [`channel`](#operationObjectChannel), and `receive` when the application should expect receiving messages from the given [`channel`](#operationObjectChannel). -channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelItemObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. +channel | [Reference Object](#referenceObject) | A `$ref` pointer to the definition of the channel in which this operation is performed. Please note the `channel` property value MUST be a [Reference Object](#referenceObject) and, therefore, MUST NOT contain a [Channel Object](#channelObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. summary | `string` | A short summary of what the operation is about. description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. security | [[Security Requirement Object](#securityRequirementObject)]| A declaration of which security mechanisms are associated with this operation. Only one of the security requirement objects MUST be satisfied to authorize an operation. In cases where Server Security also applies, it MUST also be satisfied.