AsyncAPI with CloudEvents

cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml

@@ -0,0 +1,39 @@
+# yaml-language-server: $schema=https://asyncapi.com/schema-store/3.0.0-without-$id.json
+asyncapi: 3.0.0
+info:
+  title: Light Switch Events With CloudEvents as Headers (Binary Mode)
+  version: 1.0.0
+  description: Informes about light swich changes.
+operations:
+  onOfficeLightSwitchChanged:
+    title: Office light switch was triggered
+    channel:
+      $ref: '#/channels/officeLightSwitchChanged'
+    action: receive
+
+channels:
+  officeLightSwitchChanged:
+    address: 'lightswitch.office.changed'
+    title: Office light switch changes
+    messages:
+      lightSwitchChanged:
+        $ref: '#/components/messages/lightSwitchChanged'
+
+components:
+  messages:
+    lightSwitchChanged:
+      description: Light switch was triggered event with CloudEvents headers
+      traits:
+      - $ref: 'https://raw.githubusercontent.com/Lazzaretti/asyncapi-with-cloudevents-traits/main/traits/cloudevents-headers-kafka-binary.yaml'
+      payload:
+        type: object
+        properties:
+          lightSwitchId:
+            type: integer
+            examples:
+            - 1
+          position:
+            type: string
+            enum:
+            - ON
+            - OFF

cloudevents/working-drafts/asyncapi-examples/light-switch-events-structured-json.yaml

@@ -0,0 +1,42 @@
+# yaml-language-server: $schema=https://asyncapi.com/schema-store/3.0.0-without-$id.json
+asyncapi: 3.0.0
+info:
+  title: Light Switch Events With CloudEvents as Headers (Binary Mode)
+  version: 1.0.0
+  description: Informes about light swich changes.
+operations:
+  onOfficeLightSwitchChanged:
+    title: Office light switch was triggered
+    channel:
+      $ref: '#/channels/officeLightSwitchChanged'
+    action: receive
+
+channels:
+  officeLightSwitchChanged:
+    address: 'lightswitch.office.changed'
+    title: Office light switch changes
+    messages:
+      lightSwitchChanged:
+        $ref: '#/components/messages/lightSwitchChanged'
+
+components:
+  messages:
+    lightSwitchChanged:
+      description: Light switch was triggered event with CloudEvents headers
+      payload:
+        type: object
+        allOf:
+        - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/formats/cloudevents.json'
+        properties:
+          data:
+            type: object
+            properties:
+              lightSwitchId:
+                type: integer
+                examples:
+                - 1
+              position:
+                type: string
+                enum:
+                - ON
+                - OFF

cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml

@@ -0,0 +1,56 @@
+name: cloudevents-headers-kafka-binary
+summary: Message headers for CloudEvents in binary content mode with Kafka (see https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/kafka-protocol-binding.md)
+headers:
+  type: object
+  required:
+  - ce_id
+  - ce_source
+  - ce_specversion
+  - ce_type
+  properties:
+    ce_id:
+      type: string
+      minLength: 1
+      description: Identifies the event.
+      examples:
+      - "1234-1234-1234"
+    ce_source:
+      type: string
+      format: uri-reference
+      minLength: 1
+      description: Identifies the context in which an event happened.
+      examples:
+      - "https://example.com/storage/tenant/container"
+    ce_specversion:
+      type: string
+      description: The version of the CloudEvents specification which the event uses.
+      enum:
+      - "1.0"
+    ce_type:
+      type: string
+      minLength: 1
+      description: Describes the type of event related to the originating occurrence.
+      examples:
+      - "com.example.someevent"
+    content-type:
+      type: string
+      description: Kafka default field to describing the content type of the data. Must be mapped directly to the CloudEvents datacontenttype attribute.
+      examples:
+      - "application/avro"
+      - "application/json;charset=utf-8"
+    ce_dataschema:
+      type: string
+      description: Identifies the schema that data adheres to.
+      examples:
+      - "http://registry.com/schema/v1/much.json"
+    ce_subject:
+      type: string
+      description: Describes the subject of the event in the context of the event producer (identified by source)
+      examples:
+      - mynewfile.jpg
+    ce_time:
+      type: string
+      format: date-time
+      description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
+      examples:
+      - "2018-04-05T17:31:00Z"

cloudevents/working-drafts/asyncapi.md

@@ -0,0 +1,32 @@
+# AsyncAPI With CloudEvents
+
+This document describes how CloudEvents can be defined in [AsyncAPI v3](https://www.asyncapi.com/docs/reference/specification/v3.0.0).
+It was created as a follow-up after discussion [cloudevents/spec#1276](https://github.com/cloudevents/spec/issues/1276).
+
+## Purpose
+
+Asynchronous APIs, e.g., events, can be specified in AsyncAPI, similar to how RESTful APIs can be specified in [OpenAPI](https://swagger.io/specification/).
+When defining new events in an API-first approach it can be hard to add CloudEvents headers or fields according to spec.
+This makes following the standard harder.
+This document should clarify how CloudEvents headers can be specified in AsyncAPI.
+
+## Usage
+
+Depending on the protocol and the mode (binary/structured), the inclusion of the CloudEvents fields varies.
+
+## Structured Mode
+
+In structured mode, the entire event, attributes, and data are encoded in the message body.
+When using structured mode, the usage only varies depending on the serialization format:
+
+| Format | Example                                                                 | Include                                  |
+| ------ | ----------------------------------------------------------------------- | ---------------------------------------- |
+| JSON   | [Example](./asyncapi-examples/light-switch-events-structured-json.yaml) | [Reference](../formats/cloudevents.json) |
+
+## Binary Mode
+
+In binary mode, protocol-specific bindings are mapping fields to protocol content-type metadata property or headers; therefore, the AsyncAPI format needs to depend on the protocol:
+
+| Protocol Binding                               | Example                                                              | Trait                                                            |
+| ---------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| [Kafka](../bindings/kafka-protocol-binding.md) | [Example](./asyncapi-examples/light-switch-events-binary-kafka.yaml) | [Trait](./asyncapi-traits/cloudevents-headers-kafka-binary.yaml) |