doc: getting started with traits

[fmvilas]

What?

Write a chapter of the getting started guide expanding on reusability. It should go right after #6.

We should keep it simple and explain how to reuse parts of a message or operation by using traits.

We should not mention anything about other reusable components. At most, just provide a link to the spec for the curious. The whole idea is to keep it simple and to the point. No need to explain everything in a single chapter.

Why?

To introduce the traits feature and its purpose.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[ghost]

Hi!

I just want to cross-reference my Slack discussion on this:
https://asyncapi.slack.com/archives/C34F2JV0U/p1588916689469300

My general problem here was that my assumption of traits is that they won't override the existing attributes of the "target" where they are apply. This is at least how traits worked in the context I've seen them before.

Since there seem to be different understandings and interpretations of it I'd propose to explicitly state the behavior of traits and it's consequences (e.g. In the current implementation they can't be used to provide defaults)

Example:

{
    "asyncapi": "2.0.0",
    "components": {
      "messages": {
        "Message1": {
          "headers": {
              "datacontenttype": {
                "const": "text/xml"
              }
            }
          },
          "traits": [
            {
              "$ref": "#/components/messageTraits/CloudEventsContext"
            }
          ]
        }
      },
      "messageTraits": {
        "CloudEventsContext": {
          "headers": {
            "type": "object",
            "properties": {
              "datacontenttype": {
                "description": "Content type of the data value. Must adhere to RFC 2046 format.",
                "type": "string",
                "const": "application/json"
              }
            }
          }
        }
      }
    }
  }

After traits are applied, the message will effectively have "const": "application/json". Verified this behavior on playground

[ghost]

Also maybe related:

It would be very helpful to have concrete guidance and even better - a flow diagram - how traits, $ref (and maybe $allOf) plays together in which order to create a final, denormalized representation:

https://asyncapi.slack.com/archives/C34F2JV0U/p1588917213473500

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴
It will be closed in 30 days if no further activity occurs. To unstale this issue, add a comment with detailed explanation.
Thank you for your contributions ❤️

[derberg]

@alequetzalli you might want to have it in documentation dashboard 😄

[quetzalliwrites]

@derberg done! Moved to Docs Board and triaged in To-Do column. 👩🏻‍💻

[ro4i7]

Hello @alequetzalli @fmvilas

is this issue still open if it is then please assign it to me; and also please give feedback on my below solution ;

In the previous section, we learned how to define messages and operations in an AsyncAPI document. Now, let's explore how to reuse parts of a message or operation by using traits.

What are Traits?

A trait is a reusable piece of a schema that can be applied to a message or operation. Traits allow us to avoid repeating the same definitions multiple times in our document. With traits, we can define a piece of schema once and apply it to different parts of our document.

Defining a Trait

To define a trait, we use the traits section in our AsyncAPI document. Let's define a trait that we can apply to different messages:

traits:
  color:
    type: string
    enum:
      - red
      - green
      - blue

In this example, we defined a trait called color that is a string with three possible values: red, green, and blue.

Applying a Trait

Now, let's see how we can apply this trait to a message. We use the traits keyword in our message definition to specify the trait we want to apply:

channels:
  user/signedup:
    publish:
      message:
        traits:
          - color
        properties:
          name:
            type: string
          email:
            type: string

In this example, we defined a message for a user signup event. We applied the color trait to this message, which means that it will have the type and enum properties defined in the trait.

Conclusion

Traits are a powerful feature in AsyncAPI that allows us to avoid repeating ourselves in our document. By defining reusable pieces of schema, we can create more modular and maintainable AsyncAPI documents. In the next section, we will learn about another way to achieve reusability in AsyncAPI: referencing external files.

[quetzalliwrites]

Hey @ro4i7, please don't spam an issue by copy/pasting your entire written content idea to the threads of comments. The appropriate way to submit a contribution idea is to open a PR with your contribution and then you can tag us to review or link to it in the issue. If you wrote this, and would like to propose this a contribution for this doc, then please open a PR with this content/all info needed.

Question: Did you write this, or did you generate it with ChatGPT?

[Aditi2k5]

Hi, am Aditi looking to contribute towards Async API. Could I work on this issue?