fix: keep mqtt5 and mercure as AsyncAPI 3 binding names

The AsyncAPI 3.0 and 3.1 specification text lists mqtt5 and mercure as fixed
fields of the bindings objects; only the JSON schemas leave them out. Follow the
normative text, so mqtt5 is written and read under its own key in 3.x instead of
x-mqtt5.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: bielu

src/ByteBard.AsyncAPI/Models/AsyncApiBindingKeys.cs

@@ -15,11 +15,12 @@
     /// </remarks>
     public static class AsyncApiBindingKeys
     {
-        // Every binding named by a bindings object in the AsyncAPI 3.0 and 3.1 JSON schemas.
+        // Every binding the AsyncAPI 3.0 and 3.1 specifications name in a bindings object. The prose is normative; the
+        // JSON schemas omit mqtt5 and mercure, but the specification text lists them as fixed fields.
         private static readonly HashSet<string> SpecificationKeys = new HashSet<string>(StringComparer.Ordinal)
         {
-            "amqp", "amqp1", "anypointmq", "googlepubsub", "http", "ibmmq", "jms", "kafka", "mqtt", "nats", "pulsar",
-            "redis", "ros2", "sns", "solace", "sqs", "stomp", "ws",
+            "amqp", "amqp1", "anypointmq", "googlepubsub", "http", "ibmmq", "jms", "kafka", "mercure", "mqtt", "mqtt5",
+            "nats", "pulsar", "redis", "ros2", "sns", "solace", "sqs", "stomp", "ws",
         };
 
         /// <summary>

test/ByteBard.AsyncAPI.Tests/Bindings/CustomBindingKey_Should.cs

@@ -174,7 +174,8 @@ public void BindingKeyWithExtensionPrefix_ReadsAndWritesAsBinding(AsyncApiVersio
         [TestCase("kafka", true)]
         [TestCase("ws", true)]
         [TestCase("ros2", true)]
-        [TestCase("mqtt5", false)]
+        [TestCase("mqtt5", true)]
+        [TestCase("mercure", true)]
         [TestCase("signalr", false)]
         [TestCase("x-signalr", false)]
         public void IsSpecificationKey_ReturnsWhetherAsyncApi3DefinesTheBinding(string key, bool expected)
@@ -185,7 +186,7 @@ public void IsSpecificationKey_ReturnsWhetherAsyncApi3DefinesTheBinding(string k
         [TestCase("kafka", "kafka")]
         [TestCase("signalr", "x-signalr")]
         [TestCase("x-signalr", "x-signalr")]
-        [TestCase("mqtt5", "x-mqtt5")]
+        [TestCase("mqtt5", "mqtt5")]
         public void ToV3Key_PrefixesKeysAsyncApi3DoesNotDefine(string key, string expected)
         {
             AsyncApiBindingKeys.ToV3Key(key).Should().Be(expected);

test/ByteBard.AsyncAPI.Tests/Bindings/MQTT5/MQTT5Bindings_Should.cs

@@ -54,12 +54,9 @@ public void ServerBinding_ReadsAndRoundTripsSchemaAndReference(AsyncApiVersion v
             var parsers = ByteBard.AsyncAPI.Bindings.BindingsCollection.MQTT;
             parsers.Add(new MQTT5ServerBinding());
             var reader = new AsyncApiStringReader(new AsyncApiReaderSettings { Bindings = parsers });
-
-            // AsyncAPI 3 dropped the mqtt5 binding, so a 3.x document carries it as an extension.
-            var key = version == AsyncApiVersion.AsyncApi2_0 ? "mqtt5" : "x-mqtt5";
-            var yaml = (version == AsyncApiVersion.AsyncApi2_0 ? "url: localhost\nprotocol: mqtt\n" : "host: localhost\nprotocol: mqtt\n") + $$"""
+            var yaml = (version == AsyncApiVersion.AsyncApi2_0 ? "url: localhost\nprotocol: mqtt\n" : "host: localhost\nprotocol: mqtt\n") + """
                 bindings:
-                  {{key}}:
+                  mqtt5:
                     sessionExpiryInterval:
                       $ref: '#/components/schemas/interval'
                 """;
@@ -75,9 +72,9 @@ public void ServerBinding_ReadsAndRoundTripsSchemaAndReference(AsyncApiVersion v
             roundTripDiagnostics.Errors.Should().BeEmpty();
             (reparsed.Bindings["mqtt5"] as MQTT5ServerBinding).SessionExpiryInterval.Should().BeOfType<MQTTIntegerSchema>().Which.Schema.Should().BeOfType<AsyncApiJsonSchemaReference>();
 
-            var schemaYaml = (version == AsyncApiVersion.AsyncApi2_0 ? "url: localhost\nprotocol: mqtt\n" : "host: localhost\nprotocol: mqtt\n") + $$"""
+            var schemaYaml = (version == AsyncApiVersion.AsyncApi2_0 ? "url: localhost\nprotocol: mqtt\n" : "host: localhost\nprotocol: mqtt\n") + """
                 bindings:
-                  {{key}}:
+                  mqtt5:
                     sessionExpiryInterval:
                       type: integer
                       minimum: 1

test/ByteBard.AsyncAPI.Tests/Bindings/Registration/BindingsCollection_Should.cs

@@ -57,9 +57,7 @@ public void Reader_uses_all_to_parse_field_and_new_server_bindings(AsyncApiVersi
             ros2.RmwImplementation.Should().Be("rmw_fastrtps_cpp");
             ros2.DomainId.Should().Be(7);
 
-            // AsyncAPI 3 dropped the mqtt5 binding, so a 3.x document carries it as an extension.
-            var mqtt5Key = version == AsyncApiVersion.AsyncApi2_0 ? "mqtt5" : "x-mqtt5";
-            var mqtt5Binding = reader.ReadFragment<AsyncApiServer>(serverAddress + "protocol: mqtt5\nbindings:\n  " + mqtt5Key + ": {}\n", version, out var mqtt5Diagnostics);
+            var mqtt5Binding = reader.ReadFragment<AsyncApiServer>(serverAddress + "protocol: mqtt5\nbindings:\n  mqtt5: {}\n", version, out var mqtt5Diagnostics);
             mqtt5Diagnostics.Errors.Should().BeEmpty();
             mqtt5Diagnostics.Warnings.Should().BeEmpty();
             mqtt5Binding.Bindings.Should().ContainSingle(binding => binding.Key == "mqtt5");

website/docs/bindings/mqtt5.md

@@ -87,7 +87,7 @@ if (referenceServer.Bindings.TryGetValue<MQTT5ServerBinding>(out var referenced)
 
 `TryGetValue<TBinding>` returns `false` if no binding with that type's `BindingKey` is present; the union pattern then distinguishes the scalar and schema values.
 
-The union is also used by MQTT's server and operation fields. MQTT 5's binding is deprecated, and `BindingsCollection.MQTT5` has no channel, operation, or message parser. AsyncAPI 2.x and 3.x serialization are supported; specify a target version when serializing. AsyncAPI 3 has no `mqtt5` binding, so a 3.x document carries it as `x-mqtt5` (see [custom bindings](/docs/guides/custom-bindings)). See the [shared guide](index.md).
+The union is also used by MQTT's server and operation fields. MQTT 5's binding is deprecated, and `BindingsCollection.MQTT5` has no channel, operation, or message parser. AsyncAPI 2.x and 3.x serialization are supported; specify a target version when serializing. See the [shared guide](index.md).
 
 ## Object model
 

website/docs/guides/custom-bindings.mdx

@@ -51,7 +51,7 @@ var document = new AsyncApiStringReader(settings).Read(input, out var diagnostic
 
 ## Binding keys in AsyncAPI 3
 
-AsyncAPI 3 bindings objects only allow the binding names the specification lists (`amqp`, `http`, `kafka`, `ws` and so on) and `x-` extensions. When a document is serialized as AsyncAPI 3, a binding whose `BindingKey` is not one of those names is written as an extension: `FooBinding` above appears as `x-foo`. The key in the object model stays `foo`, so `channel.Bindings["foo"]` and `TryGetValue<FooBinding>` work as before. `AsyncApiBindingKeys.ToV3Key` returns the name a key is written under. AsyncAPI 2 allows any key, so AsyncAPI 2 documents keep `foo`. A binding whose `BindingKey` already starts with `x-` is written and read under that key in both versions.
+AsyncAPI 3 bindings objects only allow the binding names the specification lists (`amqp`, `http`, `kafka`, `ws` and so on) and `x-` extensions. The list follows the specification text, which also names `mqtt5` and `mercure` even though the AsyncAPI 3 JSON schemas leave them out. When a document is serialized as AsyncAPI 3, a binding whose `BindingKey` is not one of those names is written as an extension: `FooBinding` above appears as `x-foo`. The key in the object model stays `foo`, so `channel.Bindings["foo"]` and `TryGetValue<FooBinding>` work as before. `AsyncApiBindingKeys.ToV3Key` returns the name a key is written under. AsyncAPI 2 allows any key, so AsyncAPI 2 documents keep `foo`. A binding whose `BindingKey` already starts with `x-` is written and read under that key in both versions.
 
 When reading an AsyncAPI 3 document, `x-foo` is read as the binding if a parser for `foo` is registered; otherwise it stays an extension. A registered custom binding under its bare key (`foo`) is still read, but the reader reports an error, since the document does not conform to the specification.