✅ Deploy Preview for springwolf-ui canceled.

Yes, Asyncapi and OpenAPI schema formats are quite similar. The main difference lies in the area of ​​inheritance. Schema classes with defined discriminator fields and values ​​are not (well) implemented by Asyncapi. That was the original motivation for this pull request.

The main reason for not using the payload schema format for the headers was that the headers are usually so simple that there are no differences between AsyncAPI and OpenAPI.

I thought it would unnecessarily bloat the resulting AsyncAPI by turning every headers block into a MultiSchemaFormat header:

headers:
  type: object
  properties:
    my-header-1:
      type: string
      description: Header 1
    my-header-2:
      type: string
      description: Header 2

to

headers:
  schemaFormat: application/vnd.oai.openapi;version=3.0.0
  schema:
    type: object
    properties:
      my-header-1:
        type: string
        description: Header 1
      my-header-2:
        type: string
        description: Header 2

But I must admit that the overhead is not that large at all. So - It might simplify the implementation if the schemaformat is used globally for payload and headers.

I would try change the PR towards a global asyncapi schemaformat. What do you think is a good propertyname / Enum classname instead of 'PayloadSchemaFormat'? Simply 'SchemaFormat' (which already exists), 'AsyncApiSchemaFormt' oder 'OutputSchemaFormat' ?

Sounds good. Since it is the configuration for schemaFormat, it can also be called SchemaFormat. If that is confusing with the asyncapi one, maybe SchemaFormatConfig?

I am mostly concerned about complexity and maintainability in the long term. We are a small team, so the easier it is now (also to contribute) the more features and less bugs are shipped.

A bloated document can be improved later as an optimisation, possibly also via a serialiser.

(Actually, I was considering if it is easier, when internally everything is a MultiFormatSchema and therefore less checking if this else that)