[v3] Support multi format schemas in message headers

[smoya]

Description

The current v3 spec mentions that the Message Object headers must be of type "object". Literally says:

Schema definition of the application headers. Schema MUST be of type "object". It MUST NOT define the protocol headers. If this is a Schema Object, then the schemaFormat will be assumed to be "application/vnd.aai.asyncapi+json;version=asyncapi" where the version is equal to the AsyncAPI Version String.

Since the introduction of the support of multi-format schemas, message headers also support different schema formats.
Then, in my head, reading the sentence Schema MUST be of type "object". sounds confusing to me, especially for formats like Avro, where (afaik) there is no such type but record iirc.
This constraint is also in place in the AsyncAPI JSON Schema documents describing the message object. See https://github.com/asyncapi/spec-json-schemas/blob/next-major-spec/definitions/3.0.0/messageObject.json#L21-L27

Is that restriction in place with the purpose of limiting and simplifying what a header looks like? Shall we keep it and update it according to different possible shapes depending on the format? Or rather, after the recent changes, should we get rid of it?

Relates to #622

cc @GreenRover @dalelane @derberg @jonaslagoni @fmvilas

[derberg]

yeah, sounds like Schema MUST be of type "object" is just a left over that should be removed. I don't think it is needed.

[GreenRover]

I vote for keep headers to be only async-api schema formated. To keep it simple. I see no benefit from defining header for example as avro.

[smoya]

I vote for keep headers to be only async-api schema formated. To keep it simple. I see no benefit from defining header for example as avro.

But the spec now says they allow multi-format schemas https://github.com/asyncapi/spec/blob/next-major-spec/spec/asyncapi.md#fixed-fields-16.
Do you suggest we revert that? Remember that they also support defining AsyncAPI Schemas right directly without having to specify the format.

[GreenRover]

Ok, my memories slowly come back. I guess Fran brought an reasons that required non ansycapi-schema as header.
But you @smoya only have concerns about the wording?

What i wanted to say is: Schema MUST be of type "object".
A headers have to be some kind of map.
A string/number like in the body is not valid.

[smoya]

But you @smoya only have concerns about the wording?

Not just wording. As I mentioned in the issue description, that statement goes further as it's in the messageObject JSON Schema https://github.com/asyncapi/spec-json-schemas/blob/next-major-spec/definitions/3.0.0/messageObject.json#L21-L27

[fmvilas]

I think we should leave the sentence Schema MUST be of type "object" but change it to be broader in terms of the schema formats it supports. For instance, Schema MUST represent a map of key-value pairs..

I guess Fran brought an reasons that required non ansycapi-schema as header.

We should be able to support, at least, Avro because that's what the majority of the Kafka folks are using. Making them write the same information in JSON Schema just to use it in AsyncAPI is not fair.

[smoya]

Schema MUST represent a map of key-value pairs.

Sounds like a more generic term, also not tied to JSON Schema, which is the intention.

We should be able to support, at least, Avro because that's what the majority of the Kafka folks are using. Making them write the same information in JSON Schema just to use it in AsyncAPI is not fair.

I would say we must support all of the schema formats anyway. This also simplifies the schemas and tooling IMHO. No special behavior or exceptions when treating schemas.

[smoya]

FYI, asyncapi/spec-json-schemas#370 got merged and support for all multiple formats is also included for headers.

If there is a strong reason to revert that, please feel free to say it. Otherwise, if all agree, and after merging #952, we could close this issue .

[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 ❤️