feat: support relative URI resolution in $dynamicRef (#2928) (#2945)

* feat: support relative URI resolution in $dynamicRef (#2928)

Set ExternalResource on non-fragment $dynamicRef references so the
workspace loader can discover and fetch external documents. Resolve
relative URIs against hostDocument.BaseUri in Target before calling
FindDocumentByBaseUri.

Tests:
- Fragment-only: ExternalResource is null
- Absolute URI: ExternalResource is set, resolves across documents
- Relative URI: ExternalResource is set, resolves against BaseUri across documents
- V31 and V32 coverage

* test: mirror V31 dynamic ref tests to V32 and fix workspace fallback

Adds 17 missing V32 test mirrors for full parity with V31 coverage.
Replaces dead '?? new OpenApiWorkspace()' fallback with null-forgiving
'!' in both V31 and V32 cross-document tests.

* fix: remove duplicate XML doc and use Uri.TryCreate for relative URI resolution

Addresses Copilot review feedback on #2945.

Author: aqeelat

src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs

@@ -455,7 +455,10 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
         {
             var nodeLocation = context.GetLocation();
             var anchorName = JsonNodeHelper.ExtractDynamicAnchorName(dynamicPointer);
-            var result = new OpenApiSchemaReference(!string.IsNullOrEmpty(anchorName) ? anchorName! : dynamicPointer, hostDocument);
+            string? externalResource = JsonNodeHelper.IsFragmentOnlyDynamicRef(dynamicPointer)
+                ? null
+                : JsonNodeHelper.ExtractDocumentUri(dynamicPointer);
+            var result = new OpenApiSchemaReference(!string.IsNullOrEmpty(anchorName) ? anchorName! : dynamicPointer, hostDocument, externalResource);
             var referenceMetadata = new OpenApiSchema();
             jsonObject.ParseMap(referenceMetadata, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument, context,
                 static (schema, name, value) =>

src/Microsoft.OpenApi/Reader/V32/OpenApiSchemaDeserializer.cs

@@ -455,7 +455,10 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
         {
             var nodeLocation = context.GetLocation();
             var anchorName = JsonNodeHelper.ExtractDynamicAnchorName(dynamicPointer);
-            var result = new OpenApiSchemaReference(!string.IsNullOrEmpty(anchorName) ? anchorName! : dynamicPointer, hostDocument);
+            string? externalResource = JsonNodeHelper.IsFragmentOnlyDynamicRef(dynamicPointer)
+                ? null
+                : JsonNodeHelper.ExtractDocumentUri(dynamicPointer);
+            var result = new OpenApiSchemaReference(!string.IsNullOrEmpty(anchorName) ? anchorName! : dynamicPointer, hostDocument, externalResource);
             var referenceMetadata = new OpenApiSchema();
             jsonObject.ParseMap(referenceMetadata, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument, context,
                 static (schema, name, value) =>

src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

@@ -687,7 +687,8 @@ private void RegisterAnchor(OpenApiDocument document, string anchorName, IOpenAp
         /// <summary>
         /// Resolves a $dynamicRef value against the workspace's anchor registries.
         /// For fragment-only refs (#node), resolves against the host document.
-        /// For URI refs (absolute), finds the external document and resolves there.
+        /// For URI refs (absolute or relative), finds the external document and resolves there.
+        /// Relative URIs are resolved against the host document's BaseUri.
         /// </summary>
         internal IOpenApiSchema? ResolveDynamicRef(OpenApiDocument hostDocument, string dynamicRef)
         {
@@ -698,7 +699,18 @@ private void RegisterAnchor(OpenApiDocument document, string anchorName, IOpenAp
             if (!JsonNodeHelper.IsFragmentOnlyDynamicRef(dynamicRef))
             {
                 var docUri = JsonNodeHelper.ExtractDocumentUri(dynamicRef);
-                targetDoc = docUri is not null ? FindDocumentByBaseUri(docUri) : null;
+                if (docUri is not null)
+                {
+                    if (!Uri.IsWellFormedUriString(docUri, UriKind.Absolute)
+                        && hostDocument.BaseUri is not null
+                        && Uri.TryCreate(hostDocument.BaseUri, docUri, out var resolved))
+                        docUri = resolved.AbsoluteUri;
+                    targetDoc = FindDocumentByBaseUri(docUri);
+                }
+                else
+                {
+                    targetDoc = null;
+                }
             }
 
             if (targetDoc is null) return null;

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDynamicRefTests.cs

@@ -38,6 +38,7 @@ public void BareDynamicRefDeserializesAsSchemaReference()
         var reference = Assert.IsType<OpenApiSchemaReference>(result);
         Assert.Equal("#category", reference.Reference.DynamicRef);
         Assert.True(reference.Reference.IsDynamicRefOnly);
+        Assert.Null(reference.Reference.ExternalResource);
     }
 
     [Fact]
@@ -634,7 +635,7 @@ public async Task AbsoluteDynamicRefResolvesAcrossDocuments()
         docA.BaseUri = new("https://example.com/main");
         docB.BaseUri = new("https://example.com/external");
 
-        var workspace = docA.Workspace ?? new OpenApiWorkspace();
+        var workspace = docA.Workspace!;
         workspace.RegisterComponents(docA);
         workspace.RegisterComponents(docB);
 
@@ -1493,14 +1494,75 @@ public async Task ExternalDynamicRefResolvesToPlainAnchorInExternalDocument()
         docA.BaseUri = new("https://example.com/main");
         docB.BaseUri = new("https://example.com/external");
 
-        var workspace = docA.Workspace ?? new OpenApiWorkspace();
+        var workspace = docA.Workspace!;
         workspace.RegisterComponents(docA);
         workspace.RegisterComponents(docB);
 
         var tree = docA.Components.Schemas["Tree"];
         var next = tree.Properties["next"];
         var reference = Assert.IsType<OpenApiSchemaReference>(next);
         Assert.True(reference.Reference.IsDynamicRefOnly);
+        Assert.Equal("https://example.com/external", reference.Reference.ExternalResource);
+        Assert.NotNull(reference.Target);
+        Assert.Same(docB.Components.Schemas["ExternalNode"], reference.Target);
+    }
+
+    [Fact]
+    public async Task ExternalDynamicRefWithRelativeUriResolvesAcrossDocuments()
+    {
+        var yamlA =
+        """
+        openapi: 3.1.0
+        info:
+          title: Doc A
+          version: 1.0.0
+        paths: {}
+        components:
+          schemas:
+            Tree:
+              type: object
+              properties:
+                next:
+                  $dynamicRef: 'external.yaml#node'
+        """;
+
+        var yamlB =
+        """
+        openapi: 3.1.0
+        info:
+          title: Doc B
+          version: 1.0.0
+        paths: {}
+        components:
+          schemas:
+            ExternalNode:
+              $dynamicAnchor: node
+              type: object
+              properties:
+                value:
+                  type: string
+        """;
+
+        using var streamA = new MemoryStream(Encoding.UTF8.GetBytes(yamlA));
+        using var streamB = new MemoryStream(Encoding.UTF8.GetBytes(yamlB));
+        var resultA = await OpenApiDocument.LoadAsync(streamA, "yaml", SettingsFixture.ReaderSettings);
+        var resultB = await OpenApiDocument.LoadAsync(streamB, "yaml", SettingsFixture.ReaderSettings);
+
+        var docA = resultA.Document;
+        var docB = resultB.Document;
+
+        docA.BaseUri = new("https://example.com/main.yaml");
+        docB.BaseUri = new("https://example.com/external.yaml");
+
+        var workspace = docA.Workspace!;
+        workspace.RegisterComponents(docA);
+        workspace.RegisterComponents(docB);
+
+        var tree = docA.Components.Schemas["Tree"];
+        var next = tree.Properties["next"];
+        var reference = Assert.IsType<OpenApiSchemaReference>(next);
+        Assert.True(reference.Reference.IsDynamicRefOnly);
+        Assert.Equal("external.yaml", reference.Reference.ExternalResource);
         Assert.NotNull(reference.Target);
         Assert.Same(docB.Components.Schemas["ExternalNode"], reference.Target);
     }