fix: read a binding registered under an x- key as that binding

A custom binding may already use an x- key (BindingKey => "x-signalr") so
its documents validate with any reader. Such a key matched the extension
pattern first and was read as a generic extension. Look up the registered
parsers before treating an x- key as an extension, in both versions.

Author: bielu

src/ByteBard.AsyncAPI.Readers/BindingDeserializer.cs

@@ -38,16 +38,20 @@ internal static AsyncApiBindings<TBinding> LoadBindings<TBinding>(
             var bindingType = typeof(TBinding).Name.Substring(1);
             foreach (var property in mapNode)
             {
+                // A registered key is read as that binding, even when it carries the x- prefix itself.
                 var key = property.Name;
-                if (version == AsyncApiVersion.AsyncApi3_0 && TryGetCustomBindingKey(property.Name, parsers, out var customKey))
+                if (!parsers.ContainsKey(key))
                 {
-                    // 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 (version == AsyncApiVersion.AsyncApi3_0 && TryGetCustomBindingKey(key, 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(key)))
+                    {
+                        property.ParseField(bindings, patternFields);
+                        continue;
+                    }
                 }
 
                 if (!parsers.TryGetValue(key, out var parser))
@@ -58,7 +62,7 @@ internal static AsyncApiBindings<TBinding> LoadBindings<TBinding>(
                     continue;
                 }
 
-                if (version == AsyncApiVersion.AsyncApi3_0 && key == property.Name && !AsyncApiBindingKeys.IsSpecificationKey(key))
+                if (version == AsyncApiVersion.AsyncApi3_0 && AsyncApiBindingKeys.ToV3Key(key) != property.Name)
                 {
                     // AsyncAPI 3 bindings objects only allow the specification's binding names and extensions. The binding
                     // is still read, and written back as x-<key>.

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

@@ -7,6 +7,8 @@
     using ByteBard.AsyncAPI.Models.Interfaces;
     using ByteBard.AsyncAPI.Readers;
     using ByteBard.AsyncAPI.Readers.Interface;
+    using ByteBard.AsyncAPI.Readers.ParseNodes;
+    using ByteBard.AsyncAPI.Writers;
     using FluentAssertions;
     using NUnit.Framework;
 
@@ -147,6 +149,28 @@ public void V3_ExtensionWithoutRegisteredBinding_ReadsAsExtension()
             channel.Bindings.Extensions.Keys.Should().BeEquivalentTo("x-other");
         }
 
+        [TestCase(AsyncApiVersion.AsyncApi2_0)]
+        [TestCase(AsyncApiVersion.AsyncApi3_0)]
+        public void BindingKeyWithExtensionPrefix_ReadsAndWritesAsBinding(AsyncApiVersion version)
+        {
+            // Arrange
+            var input =
+                """
+                bindings:
+                  x-prefixed:
+                    custom: someValue
+                """;
+
+            // Act
+            var channel = ReadChannel(input, version, out var diagnostic);
+
+            // Assert
+            diagnostic.Errors.Should().BeEmpty();
+            channel.Bindings.Extensions.Should().BeEmpty();
+            ((PrefixedBinding)channel.Bindings["x-prefixed"]).Custom.Should().Be("someValue");
+            channel.SerializeAsYaml(version).Should().BePlatformAgnosticEquivalentTo(input);
+        }
+
         [TestCase("kafka", true)]
         [TestCase("ws", true)]
         [TestCase("ros2", true)]
@@ -172,7 +196,39 @@ private static AsyncApiChannel ReadChannel(string input, AsyncApiVersion version
             var settings = new AsyncApiReaderSettings();
             settings.Bindings = BindingsCollection.Kafka;
             settings.Bindings.Add(new MyBinding());
+            settings.Bindings.Add(new PrefixedBinding());
             return new AsyncApiStringReader(settings).ReadFragment<AsyncApiChannel>(input, version, out diagnostic);
         }
     }
+
+    /// <summary>A custom binding whose key already carries the extension prefix.</summary>
+    public class PrefixedBinding : ChannelBinding<PrefixedBinding>
+    {
+        public string Custom { get; set; }
+
+        public override string BindingKey => "x-prefixed";
+
+        protected override FixedFieldMap<PrefixedBinding> FixedFieldMap => new FixedFieldMap<PrefixedBinding>()
+        {
+            { "custom", (a, n) => { a.Custom = n.GetScalarValue(); } },
+        };
+
+        public override void SerializeV2(IAsyncApiWriter writer)
+        {
+            this.SerializeProperties(writer);
+        }
+
+        public override void SerializeV3(IAsyncApiWriter writer)
+        {
+            this.SerializeProperties(writer);
+        }
+
+        public override void SerializeProperties(IAsyncApiWriter writer)
+        {
+            writer.WriteStartObject();
+            writer.WriteRequiredProperty("custom", this.Custom);
+            writer.WriteExtensions(this.Extensions);
+            writer.WriteEndObject();
+        }
+    }
 }

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`.
+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.
 
 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.