From a0c1d2cc8adc854ce30878724ae9b87b2e31ee5b Mon Sep 17 00:00:00 2001 From: Lazzaretti Date: Fri, 23 May 2025 14:18:39 +0200 Subject: [PATCH 1/5] AsyncAPI with CloudEvents Adding a first draft according to https://github.com/cloudevents/spec/issues/1276 Signed-off-by: Lazzaretti --- .../light-switch-events-binary-kafka.yaml | 39 +++++++++++++ .../light-switch-events-structured-json.yaml | 42 ++++++++++++++ .../cloudevents-headers-kafka-binary.yaml | 56 +++++++++++++++++++ cloudevents/working-drafts/asyncapi.md | 32 +++++++++++ 4 files changed, 169 insertions(+) create mode 100644 cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml create mode 100644 cloudevents/working-drafts/asyncapi-examples/light-switch-events-structured-json.yaml create mode 100644 cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml create mode 100644 cloudevents/working-drafts/asyncapi.md diff --git a/cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml b/cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml new file mode 100644 index 000000000..76ffee8d4 --- /dev/null +++ b/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 diff --git a/cloudevents/working-drafts/asyncapi-examples/light-switch-events-structured-json.yaml b/cloudevents/working-drafts/asyncapi-examples/light-switch-events-structured-json.yaml new file mode 100644 index 000000000..7e5ec465b --- /dev/null +++ b/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 diff --git a/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml b/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml new file mode 100644 index 000000000..71702a74d --- /dev/null +++ b/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" diff --git a/cloudevents/working-drafts/asyncapi.md b/cloudevents/working-drafts/asyncapi.md new file mode 100644 index 000000000..5ee665be1 --- /dev/null +++ b/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) | From 0a1b57ada317537d73d98fe562d41547ae2218c5 Mon Sep 17 00:00:00 2001 From: Lazzaretti Date: Wed, 28 May 2025 14:49:48 +0200 Subject: [PATCH 2/5] add changes from code review - remove intorudcion - wrap the lines at 80 chars - s/should/will/ - create translation files he/CN Signed-off-by: Lazzaretti --- .../languages/he/working-drafts/asyncapi.md | 2 ++ .../zh-CN/working-drafts/asyncapi.md | 6 +++++ cloudevents/working-drafts/asyncapi.md | 25 +++++++++++-------- 3 files changed, 22 insertions(+), 11 deletions(-) create mode 100644 cloudevents/languages/he/working-drafts/asyncapi.md create mode 100644 cloudevents/languages/zh-CN/working-drafts/asyncapi.md diff --git a/cloudevents/languages/he/working-drafts/asyncapi.md b/cloudevents/languages/he/working-drafts/asyncapi.md new file mode 100644 index 000000000..220f5cf65 --- /dev/null +++ b/cloudevents/languages/he/working-drafts/asyncapi.md @@ -0,0 +1,2 @@ +# AsyncAPI With CloudEvents - Version 1.0.3-wip +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../working-drafts/asyncapi.md) לבינתיים. diff --git a/cloudevents/languages/zh-CN/working-drafts/asyncapi.md b/cloudevents/languages/zh-CN/working-drafts/asyncapi.md new file mode 100644 index 000000000..9b5bd00c9 --- /dev/null +++ b/cloudevents/languages/zh-CN/working-drafts/asyncapi.md @@ -0,0 +1,6 @@ +# XML Event Format for CloudEvents - Version 1.0.3-wip + +本文档尚未被翻译，请先阅读英文[原版文档](../../../working-drafts/asyncapi.md) 。 + +如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ， +我们会尽快安排专人进行翻译。 diff --git a/cloudevents/working-drafts/asyncapi.md b/cloudevents/working-drafts/asyncapi.md index 5ee665be1..e240a9e19 100644 --- a/cloudevents/working-drafts/asyncapi.md +++ b/cloudevents/working-drafts/asyncapi.md @@ -1,23 +1,24 @@ # 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. +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 will 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. +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: +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                                  | | ------ | ----------------------------------------------------------------------- | ---------------------------------------- | @@ -25,7 +26,9 @@ When using structured mode, the usage only varies depending on the serialization ## 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: +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                                                            | | ---------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------- | From 2e5a250507a247d42a412dfd9616807098d03417 Mon Sep 17 00:00:00 2001 From: Lazzaretti Date: Wed, 28 May 2025 15:01:10 +0200 Subject: [PATCH 3/5] fix: title naming Signed-off-by: Lazzaretti --- cloudevents/languages/zh-CN/working-drafts/asyncapi.md | 2 +- cloudevents/working-drafts/asyncapi.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cloudevents/languages/zh-CN/working-drafts/asyncapi.md b/cloudevents/languages/zh-CN/working-drafts/asyncapi.md index 9b5bd00c9..b57d25718 100644 --- a/cloudevents/languages/zh-CN/working-drafts/asyncapi.md +++ b/cloudevents/languages/zh-CN/working-drafts/asyncapi.md @@ -1,4 +1,4 @@ -# XML Event Format for CloudEvents - Version 1.0.3-wip +# AsyncAPI With CloudEvents - Version 1.0.3-wip 本文档尚未被翻译，请先阅读英文[原版文档](../../../working-drafts/asyncapi.md) 。 diff --git a/cloudevents/working-drafts/asyncapi.md b/cloudevents/working-drafts/asyncapi.md index e240a9e19..662e3dd8e 100644 --- a/cloudevents/working-drafts/asyncapi.md +++ b/cloudevents/working-drafts/asyncapi.md @@ -1,4 +1,4 @@ -# AsyncAPI With CloudEvents +# AsyncAPI With CloudEvents - Version 1.0.3-wip ## Purpose From 26ace1f1466af303e93aebdaf729e34fa43286c0 Mon Sep 17 00:00:00 2001 From: Lazzaretti Date: Wed, 11 Jun 2025 14:00:41 +0200 Subject: [PATCH 4/5] Add short samples on how to add CloudEvents support to AsyncAPI Signed-off-by: Lazzaretti --- cloudevents/working-drafts/asyncapi.md | 36 ++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/cloudevents/working-drafts/asyncapi.md b/cloudevents/working-drafts/asyncapi.md index 662e3dd8e..a76d6e0fb 100644 --- a/cloudevents/working-drafts/asyncapi.md +++ b/cloudevents/working-drafts/asyncapi.md @@ -22,7 +22,24 @@ serialization format: | Format | Example                                                                 | Include                                  | | ------ | ----------------------------------------------------------------------- | ---------------------------------------- | -| JSON   | [Example](./asyncapi-examples/light-switch-events-structured-json.yaml) | [Reference](../formats/cloudevents.json) | +| JSON   | [Short Example](#json-example) [Full Example](./asyncapi-examples/light-switch-events-structured-json.yaml) | [Reference](../formats/cloudevents.json) | + +### JSON Example + +To add CloudEvents in structured mode, the following `allOf` reference needs to +be added: + +```yaml +components: + messages: + messageKey: + payload: + type: object + allOf: + - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/v1.0.2/cloudevents/formats/cloudevents.json' +``` + +See also: [Full Example](./asyncapi-examples/light-switch-events-structured-json.yaml) ## Binary Mode @@ -32,4 +49,19 @@ 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) | +| [Kafka](../bindings/kafka-protocol-binding.md) | [Short Example](#avro-example) [Full Example](./asyncapi-examples/light-switch-events-binary-kafka.yaml) | [Trait](./asyncapi-traits/cloudevents-headers-kafka-binary.yaml) | + +### Avro Example + +To add CloudEvents in binary mode, the following `traits` reference needs to +be added: + +```yaml +components: + messages: + messageKey: + traits: + - $ref: 'https://raw.githubusercontent.com/Lazzaretti/asyncapi-with-cloudevents-traits/main/traits/cloudevents-headers-kafka-binary.yaml' +``` + +See also: [Full Example](./asyncapi-examples/light-switch-events-binary-kafka.yaml) From 2c4789627eb44822c3670a4bda4ebe77c0a2da84 Mon Sep 17 00:00:00 2001 From: Lazzaretti Date: Wed, 11 Jun 2025 18:36:51 +0200 Subject: [PATCH 5/5] Change links for asyncapi-traits to location after merging Signed-off-by: Lazzaretti --- .../asyncapi-examples/light-switch-events-binary-kafka.yaml | 2 +- cloudevents/working-drafts/asyncapi.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml b/cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml index 76ffee8d4..3bd0a6982 100644 --- a/cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml +++ b/cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml @@ -24,7 +24,7 @@ components: 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' + - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml' payload: type: object properties: diff --git a/cloudevents/working-drafts/asyncapi.md b/cloudevents/working-drafts/asyncapi.md index a76d6e0fb..b44a957fd 100644 --- a/cloudevents/working-drafts/asyncapi.md +++ b/cloudevents/working-drafts/asyncapi.md @@ -61,7 +61,7 @@ components: messages: messageKey: traits: - - $ref: 'https://raw.githubusercontent.com/Lazzaretti/asyncapi-with-cloudevents-traits/main/traits/cloudevents-headers-kafka-binary.yaml' + - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml' ``` See also: [Full Example](./asyncapi-examples/light-switch-events-binary-kafka.yaml)