Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: align text about send receive and publisher and subscriber #934

Merged
merged 4 commits into from
Jun 29, 2023
Merged

docs: align text about send receive and publisher and subscriber #934

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
643dd4b
docs: align text about send receive and publisher and subscriber
derberg May 11, 2023
b4caac1
Apply suggestions from code review
derberg May 11, 2023
917fbc0
update sentence about default flag
derberg Jun 26, 2023
711d994
Merge branch 'next-major-spec' into whataboutbrokers
derberg Jun 26, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions spec/asyncapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The AsyncAPI Specification is a project used to describe message-driven APIs in
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) performs. For instance, consider the following AsyncAPI definition snippet:
The file(s) SHOULD describe the operations an [application](#definitionsApplication) performs. For instance, consider the following AsyncAPI definition snippet:

```yaml
channels:
Expand All @@ -34,11 +34,11 @@ operations:
$ref: "#/channels/userSignedUp"
```

It means that the [application](#definitionsApplication) will subscribe to the `userSignedUp` [channel](#definitionsChannel) to receive messages.
It means that the [application](#definitionsApplication) will receive messages from the `userSignedUp` [channel](#definitionsChannel).

**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:
It's NOT RECOMMENDED to derive a [receiver](#definitionsReceiver) AsyncAPI document from a [sender](#definitionsSender) 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 receiver snippet:

```yaml
operations:
Expand Down Expand Up @@ -70,8 +70,8 @@ Aside from the issues mentioned above, there may also be infrastructure configur
- [Definitions](#definitions)
- [Server](#definitionsServer)
- [Application](#definitionsApplication)
- [Producer](#definitionsProducer)
- [Consumer](#definitionsConsumer)
- [Sender](#definitionsSender)
- [Receiver](#definitionsReceiver)
- [Message](#definitionsMessage)
- [Channel](#definitionsChannel)
- [Protocol](#definitionsProtocol)
Expand Down Expand Up @@ -123,22 +123,22 @@ Aside from the issues mentioned above, there may also be infrastructure configur
## <a name="definitions"></a>Definitions

### <a name="definitionsServer"></a>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.
A server MAY be a message broker that is capable of sending and/or receiving between a [sender](#definitionsSender) and [receiver](#definitionsReceiver). A server MAY be a service with WebSocket API that enables message-driven communication between browser-to-server or server-to-server.

### <a name="definitionsApplication"></a>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).
An application is any kind of computer program or a group of them. It MUST be a [sender](#definitionsSender), a [receiver](#definitionsReceiver) or both. An application MAY be a microservice, IoT device (sensor), mainframe process, or a message broker 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).
derberg marked this conversation as resolved.
Show resolved Hide resolved

### <a name="definitionsProducer"></a>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.
### <a name="definitionsSender"></a>Sender
A sender is a type of application, that is sending [messages](#definitionsMessage) to [channels](#definitionsChannel). A sender MAY be publishing to multiple channels depending on the [server](#definitionsServer), protocol, and use-case pattern.
derberg marked this conversation as resolved.
Show resolved Hide resolved

### <a name="definitionsConsumer"></a>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.
### <a name="definitionsReceiver"></a>Receiver
A receiver is a type of application, that is receiving [messages](#definitionsMessage) from [channels](#definitionsChannel). A receiver MAY be receiving from multiple channels depending on the [server](#definitionsServer), protocol, and the use-case pattern. A receiver MAY send received message further without changing it. A receiver MAY act as a consumer and react to the message. A receiver MAY act as a processor that, for example, aggregates multiple messages in one and sends it further.
derberg marked this conversation as resolved.
Show resolved Hide resolved

### <a name="definitionsMessage"></a>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.

### <a name="definitionsChannel"></a>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.
A channel is an addressable component, made available by the [server](#definitionsServer), for the organization of [messages](#definitionsMessage). [Sender](#definitionsSender) applications send messages to channels and [receiver](#definitionsReceiver) applications receive 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.

### <a name="definitionsProtocol"></a>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.
Expand Down Expand Up @@ -1932,7 +1932,7 @@ The following properties are taken from the JSON Schema definition but their def

- description - [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation.
- format - See [Data Type Formats](#dataTypeFormat) for further details. While relying on JSON Schema's defined formats, the AsyncAPI Specification offers a few additional predefined formats.
- default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
- default - The default value represents what would be assumed by the receiver of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this change applies. This consumer has nothing to do with producer/consumer stuff.

Suggested change
- default - The default value represents what would be assumed by the receiver of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
- default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, of `type` is `string`, then `default` can be `"foo"` but cannot be `1`.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but in the end it related to schema of message,

The default value represents what would be assumed by the consumer

I think consumer here means the consumer of the message described with the schema

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But "consumer" of the JSON Schema may just be a code generation tool for the producer. So the "consumer" here would really be the producer, actually 😅

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

to be honest, in general The default value represents what would be assumed by the receiver of the input as the value of the schema if one is not provided sentence is complicated, but the concept is easy.

chatGPT gave me this as better option and I love it: It acts as a standard value to be assumed in case no specific value is provided. or Use it to specify that property has a predefined value if no other value is present

no receiver, subscriber, producer, or whatever

thoughts?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love this one:

Use it to specify that a property has a predefined value if no other value is present


Alternatively, any time a Schema Object can be used, a [Reference Object](#referenceObject) can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the `$ref` keyword MUST follow the behavior described by [Reference Object](#referenceObject) instead of the one in [JSON Schema definition](https://json-schema.org/understanding-json-schema/structuring.html#ref).

Expand Down