Avro specification inside AsycnApi file

[Lazzaretti]

I'm unsure how, or if at all, Avro is supported inside the AsyncApi file or if you can only have it as a separate reference.

In version 2, I found examples of inline Avro definitions: https://github.com/asyncapi/avro-schema-parser?tab=readme-ov-file#usage

However, in version 3, I have not found any yet. The specification states that for "Schema Object," you can only have JSON Schema Specifications.

and

Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions in place of defining them inline. It is appropriate to clarify that the $ref keyword MUST follow the behavior described by Reference Object instead of the one in JSON Schema definition.

https://www.asyncapi.com/docs/reference/specification/v3.0.0#schemaObject

Is the assumption correct that Avro is not supported inline? -> If so, it would be great to write that explicitly. -> If it is supported, an example would be great!

Describe the bug

Unclear behavior of how to add Avro schemas to AsycnApi .

To Reproduce

Read the spec: https://www.asyncapi.com/docs/reference/specification/v3.0.0

Additional context

AsyncAPI version 3.0.0

[github-actions[bot]]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[smoya]

Hi @Lazzaretti !

v3 keeps the support for declaring an Avro schema without the need of a reference. The following example uses the one you linked but converted to v3 of the spec:

asyncapi: 3.0.0
info:
  title: Example with Avro
  version: 0.1.0
channels:
  example:
    messages:
      myMessage:
        payload:
          schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
          schema:
            type: record
            name: User
            namespace: com.company
            doc: User information
            fields:
              - name: displayName
                type: string
              - name: email
                type: string
              - name: age
                type: int

Open in Studio

Regarding your statements:

The specification states that for "Schema Object," you can only have JSON Schema Specifications.

And that's true. The point is that the payload of a Message Object can be now three different things:

• Schema Object, just AsyncAPI Schema type, superset of JSON Schema
• MultiFormat Schema Object which supports several formats, including Avro.
• Reference Object

Note that the schemaFormat field is not anymore located in the Message Object but in the MultiFormat Schema Object. This allows reusing schemas in any part of your documents because it now includes the format they are written in.

After clarifying this, I can understand it might create confusion for those coming from pervious versions. We could include a statement in the Schema Object saying something like "if you need support for other formats, please check the MultiFormat Schema Object instead" (but with nice words 😅 ).

Do you think that will improve the readability and understanding of that matter @Lazzaretti ?

[Lazzaretti]

Thanks for the great explanation @smoya ! I can make a PR in the next few days to add this to the spec. I think that will be really helpful :)

[smoya]

I can make a PR in the next few days to add this to the spec. I think that will be really helpful :)

That would be awesome! 🙌 Ping me if you need help with that.