Skip to content

AsyncAPI 3 documents with custom bindings fail schema validation #66

Open

Description

@bielu

What happens

AsyncApiBindings<TBinding>.SerializeV3 writes each binding under its BindingKey unchanged. A custom binding (for example a ChannelBinding<T> with BindingKey => "signalr") is therefore written as:

channels:
  hub:
    bindings:
      signalr:
        bindingVersion: 0.1.0

In AsyncAPI 3.0 and 3.1, the server, channel, operation and message bindings objects have additionalProperties: false. They only accept the binding names the specification lists (amqp, amqp1, anypointmq, googlepubsub, http, ibmmq, jms, kafka, mqtt, nats, pulsar, redis, ros2, sns, solace, sqs, stomp, ws) and ^x- extensions. So a document that ByteBard serializes and reads back without diagnostics fails validation against the official AsyncAPI JSON Schema. The built-in mqtt5 binding has the same problem in 3.x, because AsyncAPI 3 has no mqtt5 binding.

The reader doesn't catch it either: a 3.x document with bindings.signalr loads without diagnostics as long as a parser for signalr is registered. AsyncAPI 2.x is unaffected, because its bindingsObject allows any key.

Proposal

  1. When serializing AsyncAPI 3, write a binding whose key is not a specification binding name as an extension, x-<key>. The key in the object model stays <key>, so Bindings["signalr"] and TryGetValue<T> keep working.
  2. When reading AsyncAPI 3, load x-<key> as the binding if a parser for <key> is registered (otherwise it stays an extension, as today). Still load a registered custom binding under its bare key, but report an error, since the document doesn't conform to the specification.

I have a PR ready that does this.

Activity

  1. added a commit that references this issue on Nov 4, 2026
    60e5ce6
  2. VisualBean commented on Nov 4, 2026

    @VisualBean
    Contributor

    I honestly think this is an issue with the specification for V3.
    RFC to get this changed in the spec has been created here asyncapi/spec#1251

    You'll notice a few liberties that have been taken in this library, in addition to this custom binding thing.
    Channel keys for instance, are restricted more than the specification as the specification allows for non-url safe keys (which technically aren't jsonpointer safe).
    (i've added another issue for the channel key thing asyncapi/spec#1252)

  3. bielu commented on Nov 5, 2026

    @bielu
    ContributorAuthor

    @VisualBean I agree with you, but yeah that's annoying they change it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions