fix: resolve external 3.x payload references

In 3.x a message payload reference is an AsyncApiMultiFormatSchemaReference.
Resolving an external reference only handled JSON and Avro schema
references, so an external payload such as `$ref: './payload.json'` was
never read and reported "Unable to deserialize reference". The external
content is now read as a Multi Format Schema Object, which also accepts a
plain Schema Object.

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

Author: bielu

src/ByteBard.AsyncAPI.Readers/AsyncApiJsonDocumentReader.cs

@@ -410,6 +410,11 @@ private IAsyncApiSerializable ResolveStreamReference(Stream stream, IAsyncApiRef
                         result = this.ReadFragment<AsyncApiAvroSchema>(json, diagnostic.SpecificationVersion, out fragmentDiagnostic);
                     }
 
+                    if (reference is AsyncApiMultiFormatSchemaReference)
+                    {
+                        result = this.ReadFragment<AsyncApiMultiFormatSchema>(json, diagnostic.SpecificationVersion, out fragmentDiagnostic);
+                    }
+
                     break;
 
                 case ReferenceType.Server:

test/ByteBard.AsyncAPI.Tests/Models/AsyncApiReference_Should.cs

@@ -29,6 +29,19 @@ public class AsyncApiReference_Should : TestBase
             }
             """;
 
+        private const string ExternalPayloads =
+            """
+            {
+              "schemas": {
+                "plain": { "type": "string" },
+                "multiFormat": {
+                  "schemaFormat": "application/vnd.aai.asyncapi+json;version=3.0.0",
+                  "schema": { "type": "integer" }
+                }
+              }
+            }
+            """;
+
         private static readonly TestCaseData[] ExternalFragmentCases =
         {
             new TestCaseData("/components/schemas/plain", SchemaType.String).SetArgDisplayNames("nested path"),
@@ -138,6 +151,69 @@ private static AsyncApiDocument ReadWithExternalSchemas(string yaml, out AsyncAp
             return new AsyncApiStringReader(settings).Read(yaml, out diagnostic);
         }
 
+        [TestCase("payloads.json#/schemas/plain", SchemaType.String)]
+        [TestCase("payloads.json#/schemas/multiFormat", SchemaType.Integer)]
+        public void V3_ExternalPayloadReference_ResolvesPayload(string reference, SchemaType expectedType)
+        {
+            var yaml =
+                $"""
+                asyncapi: 3.0.0
+                info:
+                  title: test
+                  version: 1.0.0
+                channels:
+                  workspace:
+                    messages:
+                      message:
+                        payload:
+                          $ref: '{reference}'
+                """;
+
+            var settings = new AsyncApiReaderSettings
+            {
+                ReferenceResolution = ReferenceResolutionSetting.ResolveAllReferences,
+                ExternalReferenceLoader = new MockStringLoader(ExternalPayloads),
+            };
+
+            var doc = new AsyncApiStringReader(settings).Read(yaml, out var diagnostic);
+
+            diagnostic.Errors.Should().BeEmpty();
+            var payload = doc.Channels["workspace"].Messages["message"].Payload;
+            payload.Should().BeOfType<AsyncApiMultiFormatSchemaReference>();
+            payload.As<AsyncApiMultiFormatSchemaReference>().UnresolvedReference.Should().BeFalse();
+            payload.Schema.As<AsyncApiJsonSchema>().Type.Should().Be(expectedType);
+            doc.SerializeAsYaml(AsyncApiVersion.AsyncApi3_0).Should().Contain($"$ref: {reference}");
+        }
+
+        [Test]
+        public void V3_ExternalPayloadReference_WithoutFragment_ResolvesPayload()
+        {
+            var yaml =
+                """
+                asyncapi: 3.0.0
+                info:
+                  title: test
+                  version: 1.0.0
+                channels:
+                  workspace:
+                    messages:
+                      message:
+                        payload:
+                          $ref: './payload.json'
+                """;
+
+            var settings = new AsyncApiReaderSettings
+            {
+                ReferenceResolution = ReferenceResolutionSetting.ResolveAllReferences,
+                ExternalReferenceLoader = new MockStringLoader("""{ "type": "boolean" }"""),
+            };
+
+            var doc = new AsyncApiStringReader(settings).Read(yaml, out var diagnostic);
+
+            diagnostic.Errors.Should().BeEmpty();
+            doc.Channels["workspace"].Messages["message"].Payload.Schema.As<AsyncApiJsonSchema>().Type.Should().Be(SchemaType.Boolean);
+        }
+
         [Test]
         public void V2_ReferencePointers()
         {
@@ -815,4 +891,4 @@ public Task<Stream> LoadAsync(Uri baseUri, Uri uri)
             return Task.FromResult(this.Load(baseUri, uri));
         }
     }
-}
+}