AsyncAPI with CloudEvents

[Lazzaretti]

Working draft for #1276

Fixes #1276

Clarify how CloudEvents headers can be specified in AsyncAPI.

Proposed Changes

• Add a first draft on how CloudEvents can be specified in AsyncAPI with an example and spec for structured mode with JSON and binary mode with Kafka.

Release Note

Define how CloudEvents headers can be specified in AsyncAPI.

Open points

• Change $ref: in cloudevents/working-drafts/asyncapi-examples/light-switch-events-binary-kafka.yaml to trait before merging. The current version is better to test the API spec. Afterwards, it should point to the main branch of the cloudevents/spec repo.

[duglin]

CI failed with:

cloudevents/working-drafts/asyncapi.md: Translation file cloudevents/languages/zh-CN/working-drafts/asyncapi.md does not exist
cloudevents/working-drafts/asyncapi.md: Translation file cloudevents/languages/he/working-drafts/asyncapi.md does not exist

you should be able to clone an existing he/CN template files and just change the href in there.

[duglin]

Overall it looks good with my limited knowledge of AsyncAPI. However, and this might be a nonsensical question, but is there anything more normative we can add? Or are "examples" really all that we can do because each use of it will need to be customized?

For example, I kind of expected there to be a "normative" file similar to https://github.com/cloudevents/spec/pull/1349/files#diff-062a9fa03bc40a7d12508a8bfb8780a43aeb9356e395385bc23cb4f810272a1b that says: "here's what the CE stuff would look like, so you should be able to point to (reference?) this in your specific usage", because everything after line 1 should be the same each time, no? Or does that not make sense?

[Lazzaretti]

Overall it looks good with my limited knowledge of AsyncAPI. However, and this might be a nonsensical question, but is there anything more normative we can add? Or are "examples" really all that we can do because each use of it will need to be customized?

For example, I kind of expected there to be a "normative" file similar to https://github.com/cloudevents/spec/pull/1349/files#diff-062a9fa03bc40a7d12508a8bfb8780a43aeb9356e395385bc23cb4f810272a1b that says: "here's what the CE stuff would look like, so you should be able to point to (reference?) this in your specific usage", because everything after line 1 should be the same each time, no? Or does that not make sense?

I agree that a small sample or snippet on how to add it would be helpful. I can add this, but due to the holidays, I will only be able to do so in two weeks.

[duglin]

@Lazzaretti do you still plan on making that change we discussed? Are you back from vacation yet?:-)

[Lazzaretti]

@Lazzaretti do you still plan on making that change we discussed? Are you back from vacation yet?:-)

@duglin I added two small examples that illustrate how to add the CloudEvents headers or traits to an asyncapi document. Does that address your input?

[duglin]

@Lazzaretti yes that helps! thanks!

[duglin]

Approved on the 6/12 call