Establish a mechanism for bindings specs to contribute schema objects for protocol headers

[GeraldLoeffler]

The consensus in bindings specs is for protocol headers (= well-known message headers defined by the server's protocol (HTTP, JMS, Anypoint MQ, ...) rather than by the message sender) to be defined in the headers field of the message binding object as schema objects. See for example the HTTP message binding object.

But this means that every AsyncAPI document using protocol headers is likely to define a schema object for some of the same well-known protocol headers. For example, for the HTTP protocol headers, an AsyncAPI document might use

message:
  bindings:
    http:
      headers:
        type: object
          properties:
            Content-Type:
              type: string
            Date:
              type: string
              pattern: "complex regex for RFC 7231 Date/Time Format"
            Accept-Charset:
              type: string
            ...

and something similar will be repeated in other AsyncAPI documents using the HTTP binding.

To reduce duplication and boilerplate, AsyncAPI binding specification should have a mechanism to provide schema objects for well-known protocol headers. AsyncAPI docs would then just reference these provided schema objects, instead of having to define their own schema objects.

[derberg]

@GeraldLoeffler I need some more explanation. The following is already supported:

asyncapi: 2.0.0
info:
  title: Account Service
  version: 1.0.0
  description: This service is in charge of processing user signups
channels:
  user/signedup:
    subscribe:
      bindings:
          http:
            headers:
              $ref: '#/components/schemas/httpHeader'
            bindingVersion: '0.1.0'
      message:
        $ref: '#/components/messages/UserSignedUp'
components:
  schemas:
    httpHeader:
      type: object
      properties:
        Content-Type:
          type: string
          enum: ['application/json']
  messages:
    UserSignedUp:
      payload:
        type: object
        properties:
          displayName:
            type: string
            description: Name of the user
          email:
            type: string
            format: email
            description: Email of the user

and I understand that this is exactly what you need, so I'm definitely missing something

[magicmatatjahu]

@derberg I think that Gerald wants to have some mechanism to add by default the well-known headers for protocols. He wrote:

But this means that every AsyncAPI document using protocol headers is likely to define a schema object for some of the same well-known protocol headers
To reduce duplication and boilerplate, AsyncAPI binding specification should have a mechanism to provide schema objects for well-known protocol headers. AsyncAPI docs would then just reference these provided schema objects, instead of having to define their own schema objects.

Your example is similar but isn't this same, because you must define these headers inside your spec and make ref to them. From issue's description I think there should be some defined schema which is used by default or which is easily accessed via ref, but you don't need define it in your spec.

Lets wait for response from Gerald :)

[derberg]

well $ref and #components/schemas is exactly for reduce duplication and boilerplate. How else would it work? even if something is well-known we should not apply it automatically to the AsyncAPI document, especially that it is binding specific, nothing to do with the spec itself.

[magicmatatjahu]

Yep, I agree with you, but lets wait for @GeraldLoeffler :) Gerald also raised this problem (mainly problem with headers in spec and bindings) in the previous SIG meeting, so you can check it in the record.

At the moment I can only suggest to have some common data (not only headers) for protocols/bindings inside the bindings repo and make $ref to them like $ref: https://raw.githubusercontent.com/asyncapi/bindings/master/http/json_schemas/common.json#headers

[GeraldLoeffler]

thanks @magicmatatjahu for interpreting my thoughts and discussing them with @derberg ;) : you're right, my concern is that schemas like httpHeader from @derberg 's example should come from the binding spec, to make it much easier for AsyncAPI docs to refer to common protocol headers.

I certainly did not want to propose to

apply it automatically to the AsyncAPI document

but rather to discuss the issue and find an uniform approach for an AsyncAPI document to reference such a common schema of protocol headers.

I do think this could be a solution:

At the moment I can only suggest to have some common data (not only headers) for protocols/bindings inside the bindings repo and make $ref to them like $ref: https://raw.githubusercontent.com/asyncapi/bindings/master/http/json_schemas/common.json#headers

However, this should be treated like the other schemas in that directory (server.json, message.json, ...), with agreed-upon filename etc., so that the $ref from the AsyncAPI docs has the same syntax for all bindings: https://raw.githubusercontent.com/asyncapi/bindings/master/http/json_schemas/common.json#headers`

[magicmatatjahu]

@GeraldLoeffler I'm happy that I understood you 😄

However, this should be treated like the other schemas in that directory (server.json, message.json, ...), with agreed-upon filename etc., so that the $ref from the AsyncAPI docs has the same syntax for all bindings:

yes exactly, that was my idea with common.json filename. If we go with tag versioning for bindings - every patch/minor/major version of binding will have separate git tag in repo, then we can still ref to appropriate version, but... writing each time https://raw.githubusercontent.com/asyncapi/bindings/master/http/json_schemas/common.json link can be annoying, so I don't know if it's possible with JSON Ref but having some shortcut for some links like https://raw.githubusercontent.com/asyncapi/bindings/master/http/json_schemas/common.json could be #bindings/http/common etc.

[GeraldLoeffler]

i propose to use sub-schemas in the main binding schema document for this. Specifically, protocol headers belong logically to the message binding object, and should typically be defined in a headers field in that message binding object. So it's logical to define a re-usable schema object for standard protocol headers in message.json (the JSON schema file for message binding objects). In that file, a sub-schema with the $id headersSchema (for example, but need to standardise this) should be defined for the protocol headers of that protocol.

See https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01#section-8.2.4 for sub-schemas and their $ids.

For example, for HTTP, the following sub-schema should be added to https://github.com/asyncapi/bindings/blob/master/http/json_schemas/message.json:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "http://asyncapi.com/bindings/http/message.json",
    ....
    "definitions": {
        "headersSchema": {
            "$id": "#headersSchema",
            "type": "object",
            "properties": {
                "Content-Type":     { "type": "string" },
                "Date":                    { "type": "string", "pattern": "complex regex for RFC 7231 Date/Time Format" },
                "Accept-Charset": { "type": "string" },
                ....
            }
        }
    }
    ...
    "properties": {
        "headers": {
            "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema",    
            "description": "A Schema object containing the definitions for HTTP-specific headers. This schema MUST be of type 'object' and have a 'properties' key."
        },
        ...
    }
}

Then, AsyncAPI documents using the HTTP bindings could use $ref: https://github.com/asyncapi/bindings/blob/master/http/json_schemas/message.json#headersSchema to re-use that protocol headers schema object.

[GeraldLoeffler]

If we go with tag versioning for bindings - every patch/minor/major version of binding will have separate git tag in repo, then we can still ref to appropriate version

agreed (but currently all binding specs are in the same GitHub repo and so will get the same tags)

[github-actions]

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

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

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

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

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