Proposal to add official CloudEvents Traits to the AsyncAPI ownership

[Lazzaretti]

It is nice to use a trait to add CloudEvents in "Binary Mode" to AsyncAPI.
Currently, there is no official Trait for CloudEvents, and some examples are floating around in various repos.
The idea was already proposed to the CloudEvents team: cloudevents/spec#1276 and discussed in a call.
We agreed it would make more sense to add such a trait to the AsyncAPI spec, as it would be more appropriate to add it to AsyncAPI, so that it can be versioned together.

To create such CloudEvents, Traits were already discussed in #1057. This issue would be the proposal to add it to the AsyncAPI Spec.

Other solutions

#432 discussed an alternative solution to the problem.

Example

I already created a first proposal for what I like to add in https://github.com/Lazzaretti/asyncapi-with-cloudevents-traits.
The trait for Kafka is here: https://github.com/Lazzaretti/asyncapi-with-cloudevents-traits/blob/main/traits/cloudevents-headers-kafka-binary.yaml

[derberg]

Hey @Lazzaretti

First of all thanks a 💯 for taking time to craft such a good issue with working examples 🙏🏼

We agreed it would make more sense to add such a trait to the AsyncAPI spec, as it would be more appropriate to add it to AsyncAPI, so that it can be versioned together.

Can you clarify? You mean having examples as part of the spec markdown?
If yes, wouldn't it be better if you create a dedicated guide on the website that we could even make you an owner of?

It is a pretty special case, the envelope - I mean, putting CloudEvents metadata inside AsyncAPI. I saw @lbroudoux wrote guides about it, and also some devrel from Google (who is no longer around) also promoted the traits approach.

I suggest a more detailed guide, can include even more concepts docs - this will basically allow you to provide more context. Like for example traits approach for binary is pretty legit, universal, and works. But people should be aware that solution with allOf works only for users of AsyncAPI Schema (superset of JSON Schema Draft 7) or JSON Schema. It will not work for people using different schemaFormats as these do not have allOf.

[Lazzaretti]

Hi @derberg,

Thanks a lot for your great input!

Adding the traits to the AsyncAPI Spec
My idea would be to add the CloudEvents traits directly to the AsyncAPI spec (or in a closely related repo). This way, the AsyncAPI community would maintain them since they're the primary users.

Since these traits use AsyncAPI features, it makes sense to version them together with AsyncAPI. This approach would help with versioning challenges—for example, a new major version of AsyncAPI might require updated traits, and having them versioned together ensures compatibility.

Guide on usage
I agree that the concepts docs would be a great place to describe usage, trait selection, and potential pitfalls. A blog post would then be perfect for promoting this feature.

Does this clarify things? What are your thoughts?

[derberg]

add the CloudEvents traits directly to the AsyncAPI spec

what does that technically mean?

the fact that it will be in the same repo, will not assure it is well updated. My experience with v3 release is that we did a lot of effort to update all the docs in https://github.com/asyncapi/website (we even delayed release because of that) and the most delayed and forgotten part was stuff from spec repo: https://github.com/asyncapi/spec/tree/master/examples

I think success is not in the "location" but how detailed the process is documented: https://github.com/asyncapi/spec/blob/master/RELEASE_PROCESS.md

[Lazzaretti]

Adding the CloudEvents trait would mean adding per binding (e.g., Kafka, MQTT, ...) a file like this one: https://github.com/cloudevents/spec/blob/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml

This can then be referred to like this (here with the CloudEvent URL):

components:
  messages:
    messageKey:
      traits:
      - $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml'

You are right, just having it in the repo will not guarantee an update with a new version; however, I think it increases the chances that it will be done.
It will likely increase the adoption with an official URL, and therefore, people will use it and check that it is up to date.

Can we create these files and then create the documentation, or what would be your preferred order?

[derberg]

ah wait, now I think I know what you want to achieve. Sorry, I did not get it at the beginning. You basically would like us to also make spec repo a place where we have official components that community can reference, right? so they can for example do asyncapi document like this?

components:
  messages:
    lightSwitchChanged:
      description: Light switch was triggered event with CloudEvents headers
      traits:
      - $ref: 'https://github.com/asyncapi/spec/blob/v3.1.0/components.yml#/components/messageTraits/cloudEventsHeaders'
      payload:
        type: object
        properties:
          lightSwitchId:
            type: integer
            examples:
            - 1
          position:
            type: string
            enum:
            - ON
            - OFF

am I right?

and we maintain components.yml file in this repo with all reusable official components:

components:
  messageTraits:
    cloudEventsHeaders:
       $ref: 'https://raw.githubusercontent.com/cloudevents/spec/main/cloudevents/working-drafts/asyncapi-traits/cloudevents-headers-kafka-binary.yaml#/headers'

[thompson-tomo]

Ideally we wouldn't need to specify the full url hence we could do

components:
  messages:
    lightSwitchChanged:
      description: Light switch was triggered event with CloudEvents headers
      traits:
      - $ref: '#/components/messageTraits/cloudEvent'
      payload:
        type: object
        properties:
          lightSwitchId:
            type: integer
            examples:
            - 1
          position:
            type: string
            enum:
            - ON
            - OFF

With #1104 the need to specify the url would only be once.

[Lazzaretti]

ah wait, now I think I know what you want to achieve. Sorry, I did not get it at the beginning. You basically would like us to also make spec repo a place where we have official components that community can reference, right? so they can for example do asyncapi document like this?

@derberg, exactly, yes, this would be the idea.

and we maintain components.yml file in this repo with all reusable official components:

I did not have the idea of the components.yml yet, but I think that would be a great document to have an overview and manage the documents in a machine-readable way!

@thompson-tomo, that can be simplification if #1104 is approved, right! I just want to add that a CloudEvents version should also be added to the name of the trait, to allow versioning on the CloudEvents side.

[thompson-tomo]

So ideally with registries aka #1104 versioning could be defined as part of the path there but could also be in the relative path.

[Lazzaretti]

@derberg, do you think this makes sense? Can you be the champion for this RFC? Should we start a PR with an initial components.yaml and a trait?

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️