fix: write custom bindings as x- extensions in AsyncAPI 3 documents

AsyncAPI 3 bindings objects only allow the specification's binding names
and x- extensions, but SerializeV3 wrote every binding under its
BindingKey, so a document with a custom binding (or the deprecated
mqtt5 binding) failed validation against the AsyncAPI JSON Schema, while
the reader accepted it without diagnostics.

When serializing AsyncAPI 3, write a binding whose key is not a
specification binding name as x-<key>; AsyncApiBindingKeys exposes the
name list and the mapping. When reading AsyncAPI 3, load x-<key> as the
binding when a parser for <key> is registered, and report an error for
a registered custom binding under its bare key (it is still read).
AsyncAPI 2 allows any key and is unchanged.

Closes #66

Author: bielu

src/ByteBard.AsyncAPI.Readers/BindingDeserializer.cs

@@ -1,7 +1,9 @@
 namespace ByteBard.AsyncAPI.Readers
 {
+    using System;
     using System.Collections.Generic;
     using System.Linq;
+    using ByteBard.AsyncAPI.Bindings;
     using ByteBard.AsyncAPI.Exceptions;
     using ByteBard.AsyncAPI.Extensions;
     using ByteBard.AsyncAPI.Models;
@@ -25,29 +27,47 @@ public static T LoadBinding<T>(string nodeName, ParseNode node, FixedFieldMap<T>
         internal static AsyncApiBindings<TBinding> LoadBindings<TBinding>(
             MapNode mapNode,
             IDictionary<string, IBindingParser<TBinding>> parsers,
-            PatternFieldMap<AsyncApiBindings<TBinding>> patternFields)
+            PatternFieldMap<AsyncApiBindings<TBinding>> patternFields,
+            AsyncApiVersion version = AsyncApiVersion.AsyncApi2_0)
             where TBinding : IBinding
         {
             var context = mapNode.Context;
             var bindings = new AsyncApiBindings<TBinding>();
+
+            // TBinding is the binding interface (e.g. IChannelBinding), so drop the leading "I" for the diagnostics.
+            var bindingType = typeof(TBinding).Name.Substring(1);
             foreach (var property in mapNode)
             {
-                if (patternFields.Keys.Any(isMatch => isMatch(property.Name)))
+                var key = property.Name;
+                if (version == AsyncApiVersion.AsyncApi3_0 && TryGetCustomBindingKey(property.Name, parsers, out var customKey))
+                {
+                    // AsyncAPI 3 writes a custom binding as an extension (x-<key>); read it back as the binding.
+                    key = customKey;
+                }
+                else if (patternFields.Keys.Any(isMatch => isMatch(property.Name)))
                 {
+                    property.ParseField(bindings, patternFields);
                     continue;
                 }
 
-                if (!parsers.TryGetValue(property.Name, out var parser))
+                if (!parsers.TryGetValue(key, out var parser))
                 {
-                    // TBinding is the binding interface (e.g. IChannelBinding), so drop the leading "I" for the diagnostic.
-                    var bindingType = typeof(TBinding).Name.Substring(1);
-
                     // Reported as an error because the binding is dropped from the model and cannot be written back.
                     context.Diagnostic.Errors.Add(
-                        new AsyncApiError(context.GetLocation(), $"{bindingType} {property.Name} is not found"));
+                        new AsyncApiError(context.GetLocation(), $"{bindingType} {key} is not found"));
                     continue;
                 }
 
+                if (version == AsyncApiVersion.AsyncApi3_0 && key == property.Name && !AsyncApiBindingKeys.IsSpecificationKey(key))
+                {
+                    // AsyncAPI 3 bindings objects only allow the specification's binding names and extensions. The binding
+                    // is still read, and written back as x-<key>.
+                    context.Diagnostic.Errors.Add(
+                        new AsyncApiError(
+                            context.GetLocation(),
+                            $"{bindingType} {key} is not an AsyncAPI 3 binding name; write a custom binding as {AsyncApiBindingKeys.ToV3Key(key)}"));
+                }
+
                 try
                 {
                     var binding = parser.LoadBinding(property);
@@ -63,11 +83,31 @@ internal static AsyncApiBindings<TBinding> LoadBindings<TBinding>(
                 }
             }
 
-            mapNode.ParseFields(bindings, patternFields);
-
             return bindings;
         }
 
+        private static bool TryGetCustomBindingKey<TBinding>(
+            string propertyName,
+            IDictionary<string, IBindingParser<TBinding>> parsers,
+            out string key)
+            where TBinding : IBinding
+        {
+            key = null;
+            if (!propertyName.StartsWith(AsyncApiConstants.ExtensionFieldNamePrefix, StringComparison.Ordinal))
+            {
+                return false;
+            }
+
+            var candidate = propertyName.Substring(AsyncApiConstants.ExtensionFieldNamePrefix.Length);
+            if (AsyncApiBindingKeys.IsSpecificationKey(candidate) || !parsers.ContainsKey(candidate))
+            {
+                return false;
+            }
+
+            key = candidate;
+            return true;
+        }
+
         private static PatternFieldMap<T> BindingPatternExtensionFields<T>()
     where T : IBinding, new()
         {

src/ByteBard.AsyncAPI.Readers/V3/AsyncApiChannelBindingDeserializer.cs

@@ -22,7 +22,7 @@ internal static AsyncApiBindings<IChannelBinding> LoadChannelBindings(ParseNode
                 return new AsyncApiBindingsReference<IChannelBinding>(pointer);
             }
 
-            return BindingDeserializer.LoadBindings(mapNode, node.Context.ChannelBindingParsers, channelBindingPatternFields);
+            return BindingDeserializer.LoadBindings(mapNode, node.Context.ChannelBindingParsers, channelBindingPatternFields, AsyncApiVersion.AsyncApi3_0);
         }
     }
 }

src/ByteBard.AsyncAPI.Readers/V3/AsyncApiMessageBindingDeserializer.cs

@@ -22,7 +22,7 @@ internal static AsyncApiBindings<IMessageBinding> LoadMessageBindings(ParseNode
                 return new AsyncApiBindingsReference<IMessageBinding>(pointer);
             }
 
-            return BindingDeserializer.LoadBindings(mapNode, node.Context.MessageBindingParsers, messageBindingPatternFields);
+            return BindingDeserializer.LoadBindings(mapNode, node.Context.MessageBindingParsers, messageBindingPatternFields, AsyncApiVersion.AsyncApi3_0);
         }
     }
 }

src/ByteBard.AsyncAPI.Readers/V3/AsyncApiOperationBindingDeserializer.cs

@@ -22,7 +22,7 @@ internal static AsyncApiBindings<IOperationBinding> LoadOperationBindings(ParseN
                 return new AsyncApiBindingsReference<IOperationBinding>(pointer);
             }
 
-            return BindingDeserializer.LoadBindings(mapNode, node.Context.OperationBindingParsers, operationBindingPatternFields);
+            return BindingDeserializer.LoadBindings(mapNode, node.Context.OperationBindingParsers, operationBindingPatternFields, AsyncApiVersion.AsyncApi3_0);
         }
     }
 }

src/ByteBard.AsyncAPI.Readers/V3/AsyncApiServerBindingDeserializer.cs

@@ -22,7 +22,7 @@ internal static AsyncApiBindings<IServerBinding> LoadServerBindings(ParseNode no
                 return new AsyncApiBindingsReference<IServerBinding>(pointer);
             }
 
-            return BindingDeserializer.LoadBindings(mapNode, node.Context.ServerBindingParsers, serverBindingPatternFields);
+            return BindingDeserializer.LoadBindings(mapNode, node.Context.ServerBindingParsers, serverBindingPatternFields, AsyncApiVersion.AsyncApi3_0);
         }
     }
 }

src/ByteBard.AsyncAPI/Models/AsyncApiBindingKeys.cs

@@ -0,0 +1,52 @@
+namespace ByteBard.AsyncAPI.Bindings
+{
+    using System;
+    using System.Collections.Generic;
+    using ByteBard.AsyncAPI.Models;
+    using ByteBard.AsyncAPI.Models.Interfaces;
+
+    /// <summary>
+    /// The binding names AsyncAPI 3 defines, and the key a binding is written under in an AsyncAPI 3 document.
+    /// </summary>
+    /// <remarks>
+    /// In AsyncAPI 3 the server, channel, operation and message bindings objects only allow the protocol names
+    /// the specification lists, plus <c>x-</c> extensions. A custom binding (one whose <see cref="IBinding.BindingKey"/>
+    /// is not listed) is therefore written as <c>x-&lt;key&gt;</c>. AsyncAPI 2 allows any key, so it keeps the key as is.
+    /// </remarks>
+    public static class AsyncApiBindingKeys
+    {
+        // Every binding named by a bindings object in the AsyncAPI 3.0 and 3.1 JSON schemas.
+        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",
+        };
+
+        /// <summary>
+        /// Whether AsyncAPI 3 defines a binding with this name.
+        /// </summary>
+        /// <param name="key">The binding key.</param>
+        /// <returns><c>true</c> for a binding the specification lists; <c>false</c> otherwise, including for <c>x-</c> keys.</returns>
+        public static bool IsSpecificationKey(string key)
+        {
+            return key != null && SpecificationKeys.Contains(key);
+        }
+
+        /// <summary>
+        /// The property name a binding is written under in an AsyncAPI 3 bindings object.
+        /// </summary>
+        /// <param name="key">The binding key.</param>
+        /// <returns>The key itself for a specification binding or an <c>x-</c> key; otherwise the key with an <c>x-</c> prefix.</returns>
+        public static string ToV3Key(string key)
+        {
+            if (key is null)
+            {
+                throw new ArgumentNullException(nameof(key));
+            }
+
+            return IsSpecificationKey(key) || key.StartsWith(AsyncApiConstants.ExtensionFieldNamePrefix, StringComparison.Ordinal)
+                ? key
+                : AsyncApiConstants.ExtensionFieldNamePrefix + key;
+        }
+    }
+}

src/ByteBard.AsyncAPI/Models/AsyncApiBindings{TBinding}.cs

@@ -3,6 +3,7 @@
     using System;
     using System.Collections;
     using System.Collections.Generic;
+    using ByteBard.AsyncAPI.Bindings;
     using ByteBard.AsyncAPI.Models.Interfaces;
     using ByteBard.AsyncAPI.Writers;
 
@@ -45,12 +46,10 @@ public virtual void SerializeV3(IAsyncApiWriter writer)
 
             foreach (var binding in this)
             {
-                var bindingType = binding.Key;
-                var bindingValue = binding.Value;
-
-                writer.WritePropertyName(bindingType);
+                // AsyncAPI 3 only allows the specification's binding names, so a custom binding is written as an extension.
+                writer.WritePropertyName(AsyncApiBindingKeys.ToV3Key(binding.Key));
 
-                bindingValue.SerializeV3(writer);
+                binding.Value.SerializeV3(writer);
             }
 
             writer.WriteExtensions(this.Extensions);

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

@@ -0,0 +1,178 @@
+namespace ByteBard.AsyncAPI.Tests.Bindings
+{
+    using System.Linq;
+    using ByteBard.AsyncAPI.Bindings;
+    using ByteBard.AsyncAPI.Bindings.Kafka;
+    using ByteBard.AsyncAPI.Models;
+    using ByteBard.AsyncAPI.Models.Interfaces;
+    using ByteBard.AsyncAPI.Readers;
+    using ByteBard.AsyncAPI.Readers.Interface;
+    using FluentAssertions;
+    using NUnit.Framework;
+
+    public class CustomBindingKey_Should : TestBase
+    {
+        [Test]
+        public void V3_CustomBinding_SerializesUnderExtensionKey()
+        {
+            // Arrange
+            var channel = new AsyncApiChannel();
+            channel.Bindings.Add(new MyBinding { Custom = "someValue", Any = new AsyncApiAny("anyValue") });
+
+            // Act
+            var actual = channel.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            // Assert
+            actual.Should().BePlatformAgnosticEquivalentTo(
+                """
+                bindings:
+                  x-my:
+                    custom: someValue
+                    any: anyValue
+                """);
+        }
+
+        [Test]
+        public void V3_SpecificationBinding_SerializesUnderItsOwnKey()
+        {
+            // Arrange
+            var channel = new AsyncApiChannel();
+            channel.Bindings.Add(new KafkaChannelBinding { Topic = "orders" });
+
+            // Act
+            var actual = channel.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0);
+
+            // Assert
+            actual.Should().Contain("kafka:");
+            actual.Should().NotContain("x-kafka");
+        }
+
+        [Test]
+        public void V2_CustomBinding_SerializesUnderItsOwnKey()
+        {
+            // Arrange
+            var channel = new AsyncApiChannel();
+            channel.Bindings.Add(new MyBinding { Custom = "someValue", Any = new AsyncApiAny("anyValue") });
+
+            // Act
+            var actual = channel.SerializeAsYaml(AsyncApiVersion.AsyncApi2_0);
+
+            // Assert
+            actual.Should().Contain("  my:");
+            actual.Should().NotContain("x-my");
+        }
+
+        [Test]
+        public void V3_CustomBindingUnderExtensionKey_ReadsAsBindingWithoutDiagnostics()
+        {
+            // Arrange
+            var input =
+                """
+                bindings:
+                  x-my:
+                    custom: someValue
+                    any: anyValue
+                """;
+
+            // Act
+            var channel = ReadChannel(input, AsyncApiVersion.AsyncApi3_0, out var diagnostic);
+
+            // Assert
+            diagnostic.Errors.Should().BeEmpty();
+            diagnostic.Warnings.Should().BeEmpty();
+            channel.Bindings.Keys.Should().BeEquivalentTo("my");
+            channel.Bindings.Extensions.Should().BeEmpty();
+            ((MyBinding)channel.Bindings["my"]).Custom.Should().Be("someValue");
+            channel.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0).Should().BePlatformAgnosticEquivalentTo(input);
+        }
+
+        [Test]
+        public void V3_CustomBindingWithoutExtensionPrefix_AddsErrorAndReadsBinding()
+        {
+            // Arrange
+            var input =
+                """
+                bindings:
+                  my:
+                    custom: someValue
+                    any: anyValue
+                """;
+
+            // Act
+            var channel = ReadChannel(input, AsyncApiVersion.AsyncApi3_0, out var diagnostic);
+
+            // Assert
+            diagnostic.Errors.Select(e => e.Message).Should().BeEquivalentTo(
+                "ChannelBinding my is not an AsyncAPI 3 binding name; write a custom binding as x-my");
+            channel.Bindings.Keys.Should().BeEquivalentTo("my");
+        }
+
+        [Test]
+        public void V2_CustomBindingWithoutExtensionPrefix_ReadsWithoutDiagnostics()
+        {
+            // Arrange
+            var input =
+                """
+                bindings:
+                  my:
+                    custom: someValue
+                    any: anyValue
+                """;
+
+            // Act
+            var channel = ReadChannel(input, AsyncApiVersion.AsyncApi2_0, out var diagnostic);
+
+            // Assert
+            diagnostic.Errors.Should().BeEmpty();
+            channel.Bindings.Keys.Should().BeEquivalentTo("my");
+        }
+
+        [Test]
+        public void V3_ExtensionWithoutRegisteredBinding_ReadsAsExtension()
+        {
+            // Arrange
+            var input =
+                """
+                bindings:
+                  x-other:
+                    custom: someValue
+                """;
+
+            // Act
+            var channel = ReadChannel(input, AsyncApiVersion.AsyncApi3_0, out var diagnostic);
+
+            // Assert
+            diagnostic.Errors.Should().BeEmpty();
+            channel.Bindings.Keys.Should().BeEmpty();
+            channel.Bindings.Extensions.Keys.Should().BeEquivalentTo("x-other");
+        }
+
+        [TestCase("kafka", true)]
+        [TestCase("ws", true)]
+        [TestCase("ros2", true)]
+        [TestCase("mqtt5", false)]
+        [TestCase("signalr", false)]
+        [TestCase("x-signalr", false)]
+        public void IsSpecificationKey_ReturnsWhetherAsyncApi3DefinesTheBinding(string key, bool expected)
+        {
+            AsyncApiBindingKeys.IsSpecificationKey(key).Should().Be(expected);
+        }
+
+        [TestCase("kafka", "kafka")]
+        [TestCase("signalr", "x-signalr")]
+        [TestCase("x-signalr", "x-signalr")]
+        [TestCase("mqtt5", "x-mqtt5")]
+        public void ToV3Key_PrefixesKeysAsyncApi3DoesNotDefine(string key, string expected)
+        {
+            AsyncApiBindingKeys.ToV3Key(key).Should().Be(expected);
+        }
+
+        private static AsyncApiChannel ReadChannel(string input, AsyncApiVersion version, out AsyncApiDiagnostic diagnostic)
+        {
+            var settings = new AsyncApiReaderSettings();
+            settings.Bindings = BindingsCollection.Kafka;
+            settings.Bindings.Add(new MyBinding());
+            return new AsyncApiStringReader(settings).ReadFragment<AsyncApiChannel>(input, version, out diagnostic);
+        }
+    }
+}