feat!: move operations to its own root object (#806)

asyncapi · Sep 26, 2022 · 1d50ccb · 1d50ccb
1 parent eef1d04
commit 1d50ccb
Showing 1 changed file with 80 additions and 46 deletions.
diff --git 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 [GitHub Issue that we use for tracking 3.0 development progress](https://github.com/asyncapi/spec/issues/691).
+
 # AsyncAPI Specification
 
 #### Disclaimer
@@ -58,6 +62,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 +173,7 @@ Field Name | Type | Description
 <a name="A2SServers"></a>servers | [Servers Object](#serversObject) | Provides connection details of servers.
 <a name="A2SDefaultContentType"></a>defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload.
 <a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication).
+<a name="A2SOperations"></a>operations | [Operations Object](#operationsObject) | The operations this [application](#definitionsApplication) MUST implement.
 <a name="A2SComponents"></a>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).
 <a name="A2STags"></a>tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique.
 <a name="A2SExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
@@ -703,37 +709,97 @@ userCompletedOrder:
 
 
 
+#### <a name="operationsObject"></a>Operations Object
+
+Holds a dictionary with all the [operations](#operationObject) this application MUST implement.
+
+> 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
+---|:---:|---
+<a name="operationsObjectOperation"></a>{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
+
+```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'
+```
+
 
 
-#### <a name="operationObject"></a>Operation Object
 
-Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.
+#### <a name="operationObject"></a>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 specific operation.
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="operationObjectOperationId"></a>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.
+<a name="operationObjectAction"></a>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).
+<a name="operationObjectChannel"></a>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.
 <a name="operationObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
 <a name="operationObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="operationObjectSecurity"></a>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.
 <a name="operationObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for API documentation control. Tags can be used for logical grouping of operations.
 <a name="operationObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationObjectBindings"></a>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.
 <a name="operationObjectTraits"></a>traits | [[Operation Trait Object](#operationTraitObject) &#124; [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.
-<a name="operationObjectMessage"></a>message | [Message Object](#messageObject) &#124; [Reference Object](#referenceObject) &#124; Map["oneOf", [[Message Object](#messageObject) &#124; [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).
 
 ##### Operation Object Example
 
 ```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 +813,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 +825,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 +838,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,15 +850,16 @@ traits:
 
 #### <a name="operationTraitObject"></a>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).
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="operationTraitObjectOperationId"></a>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.
+<a name="operationTraitObjectAction"></a>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).
+<a name="operationTraitObjectChannel"></a>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.
 <a name="operationTraitObjectSummary"></a>summary | `string` | A short summary of what the operation is about.
 <a name="operationTraitObjectDescription"></a>description | `string` | A verbose explanation of the operation. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
 <a name="operationTraitObjectSecurity"></a>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 +1506,9 @@ Field Name | Type | Description
 ---|:---|--- 
 <a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject).
 <a name="componentsServers"></a> servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject).
+<a name="componentsServerVariables"></a> serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject).
 <a name="componentsChannels"></a> channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject).
-<a name="componentsServerVariables"></a> serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). 
+<a name="componentsOperations"></a> operations | Map[`string`, [Operation Item Object](#operationObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Operation Item Objects](#operationObject).
 <a name="componentsMessages"></a> messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject).
 <a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject).
 <a name="componentsParameters"></a> parameters | Map[`string`, [Parameter Object](#parameterObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Parameter Objects](#parameterObject).