[FEATURE REQUEST] Add support for multiple schema formats

[fmvilas]

Is your feature request related to a problem? Please describe.
Some users complain because they're already using Avro or Google's protobuf, and don't want to maintain the definitions in both formats, e.g., protobuf and JSON schema. Users want to reuse their definitions without having to make weird tricks.

Can't it be tackled using specification extensions?
Absolutely. But it would require having schemas defined as "empty objects" and then a specification extension providing the real value. While this is possible, it's a weird trick, because the JSON schema definition doesn't match the, for instance, protobuf definition.

Describe the solution you'd like
See the proposal below.

Describe alternatives you've considered
Using specification extensions.

Additional context
Unlike HTTP APIs, message-oriented architectures use a wide variety of protocols and message formats. We should embrace them and don't stick too heavily to JSON schema.

Proposal

My proposal is to insert a new key into headers and payload. The key name will represent the schema format and its value will depend on the schema format.

Examples

channels:
  user/created:
    subscribe:
      headers:
        application/x-protobuf: >
          message Headers {
            string my-app-header = 1;
          }
      payload:
        application/x-protobuf: >
          message UserCreated {
            int32 id = 1;
            string name = 2;
            string email = 3;
          }

Same document but using $ref's.

channels:
  user/created:
    subscribe:
      headers:
        application/x-protobuf:
          $ref: 'path/to/user-created.proto#Headers'
      payload:
        application/x-protobuf:
          $ref: 'path/to/user-created.proto#UserCreated'

Specifying multiple schema formats is forbidden. The following is NOT VALID:

channels:
  user/created:
    subscribe:
      headers:
        application/x-protobuf:
          $ref: 'path/to/user-created.proto#Headers'
      payload:
        application/x-protobuf:
          $ref: 'path/to/user-created.proto#UserCreated'
        application/schema+json;version=draft-07:
          $ref: 'path/to/user-created.json'
        application/vnd.oai.openapi;version=3.0.1#/components/schemas/UserCreated:
          $ref: 'path/to/user-created.json'
        avro:
          $ref: 'path/to/user-created.avro'

Notice the usage of URI fragments to point to a specific Proto message.

---

Discarded solutions

Other solutions have been considered but discarded:

channels:
  user/created:
    subscribe:
      schemaType: 'application/x-protobuf'
      headers:
        $ref: 'path/to/user-created.proto#headers'
      payload:
        $ref: 'path/to/user-created.proto#payload'

channels:
  user/created:
    subscribe:
      headers:
        schemaType: 'application/x-protobuf'
        uri: 'path/to/user-created.proto#headers'
      payload:
        schemaType: 'application/x-protobuf'
        uri: 'path/to/user-created.proto#payload'

[fmvilas]

Updated the description with a proposal ☝️

[rmelian]

@fmvilas why the support for multiple schema formats? I think this adds more complexity to the spec with no much value. Do you have any use case for this?

EDIT: I mean why multiple schemas formats on the same payload. In this case we'll need to make sure all formats are valid at the same time and I'm not really seen why someone would want to define multiple formats at a time

channels:
  user/created:
    subscribe:
      headers:
        application/x-protobuf:
          $ref: 'path/to/user-created.proto#Headers'
      payload:
        application/x-protobuf:
          $ref: 'path/to/user-created.proto#UserCreated'
        application/schema+json;version=draft-07:
          $ref: 'path/to/user-created.json'
        application/vnd.oai.openapi;version=3.0.1#/components/schemas/UserCreated:
          $ref: 'path/to/user-created.json'
        avro:
          $ref: 'path/to/user-created.avro'

[fmvilas]

Good point. I'll limit them to just one. People can always create overlays (#107) if they want to change some message format.

[rmelian]

yeah, I've seen in event-driven architectures is more common to pass one format and have others processes/bus to do transformation :)

[asyncapi-bot]

🎉 This issue has been resolved in version 1.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀