docs(spec): v3.0.0-next-major-spec.8 release

pages/docs/reference/specification/v3.0.0-next-major-spec.7.md → pages/docs/reference/specification/v3.0.0-next-major-spec.8.md

@@ -16,24 +16,54 @@ The AsyncAPI Specification is licensed under [The Apache License, Version 2.0](h
 
 ## Introduction
 
-The AsyncAPI Specification is a project used to describe and document message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc).
+The AsyncAPI Specification is a project used to describe message-driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over any protocol (e.g., AMQP, MQTT, WebSockets, Kafka, STOMP, HTTP, Mercure, etc).
 
-The AsyncAPI Specification defines a set of files required to describe such an API.
-These files can then be used to create utilities, such as documentation, integration and/or testing tools.
+The AsyncAPI Specification defines a set of files required to describe the API of an [application](#definitionsApplication).
+These files can be used to create utilities, such as documentation, code, integration, or testing tools.
 
-The file(s) MUST describe the operations an [application](#definitionsApplication) accepts. For instance, consider the following AsyncAPI definition snippet:
+The file(s) MUST describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet:
 
 ```yaml
-user/signedup:
-  subscribe:
-    message:
-      $ref: "#/components/messages/userSignUp"
+channels:
+  userSignedUp:
+    # ...(redacted for brevity)
+operations:
+  onUserSignedUp:
+    action: receive
+    channel:
+      $ref: "#/channels/userSignedUp"
 ```
 
-It means that the [application](#definitionsApplication) allows [consumers](#definitionsConsumer) to subscribe to the `user/signedup` [channel](#definitionsChannel) to receive userSignUp [messages](#definitionsMessage) produced by the application.
+It means that the [application](#definitionsApplication) will subscribe to the `userSignedUp` [channel](#definitionsChannel) to receive messages.
 
 **The AsyncAPI specification does not assume any kind of software topology, architecture or pattern.** Therefore, a server MAY be a message broker, a web server or any other kind of computer program capable of sending and/or receiving data. However, AsyncAPI offers a mechanism called "bindings" that aims to help with more specific information about the protocol.
 
+It's NOT RECOMMENDED to derive a [consumer](#definitionsConsumer) AsyncAPI document from a [producer](#definitionsProducer) one or vice versa. There are no guarantees that the channel used by an application to receive messages will be the same channel where another application is sending them. Also, certain fields in the document like `summary`, `description`, and the id of the operation might stop making sense. For instance, given the following consumer snippet:
+
+```yaml
+operations:
+  onUserSignedUp:
+    summary: On user signed up.
+    description: Event received when a user signed up on the product.
+    action: receive
+    channel:
+      $ref: "#/channels/userSignedUp"
+```
+
+We can't automatically assume that an _opposite_ application exists by simply replacing `receive` with `send`:
+
+```yaml
+operations:
+  onUserSignedUp: # <-- This doesn't make sense now. Should be something like sendUserSignedUp.
+    summary: On user signed up. # <-- This doesn't make sense now. Should say something like "Sends a user signed up event".
+    description: Event received when a user signed up on the product. # <-- This doesn't make sense now. Should speak about sending an event, not receiving it.
+    action: send
+    channel:
+      $ref: "#/channels/userSignedUp"
+```
+
+Aside from the issues mentioned above, there may also be infrastructure configuration that is not represented here. For instance, a system may use a read-only channel for receiving messages, a different one for sending them, and an intermediary process that will forward messages from one channel to the other.
+
 
 ## <a name="definitions"></a>Definitions
 
@@ -760,7 +790,7 @@ Describes a specific operation.
 
 Field Name | Type | Description
 ---|:---:|---
-<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="operationObjectAction"></a>action | `"send"` &#124; `"receive"` | **Required**. 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="operationObjectTitle"></a>title | `string` | A human-friendly title for the operation.
 <a name="operationObjectSummary"></a>summary | `string` | A short summary of what the operation is about.

public/_redirects

@@ -22,8 +22,8 @@ https://www.asyncapi.io/* https://www.asyncapi.com/:splat 301!
 # LATEST-SPEC-REDIRECTION:END
 
 # SPEC-REDIRECTION:START
+/docs/reference/specification/3.0.0-next-major-spec.8 /docs/reference/specification/v3.0.0-next-major-spec.8 302!
 /docs/reference/specification/2.6.0 /docs/reference/specification/v2.6.0 302!
-/docs/reference/specification/3.0.0-next-major-spec.7 /docs/reference/specification/v3.0.0-next-major-spec.7 302!
 /docs/reference/specification/2.5.0 /docs/reference/specification/v2.5.0 302!
 /docs/reference/specification/2.4.0 /docs/reference/specification/v2.4.0 302!
 /docs/reference/specification/2.3.0 /docs/reference/specification/v2.3.0 302!