Resolve external document dereference to OpenApiDocument using $ref to $id

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

@@ -157,9 +157,14 @@ private static (string, string) GetReferenceIdAndExternalResource(string pointer
             string refId = !pointer.Contains('#') ? pointer : refSegments.Last();
 
             var isExternalResource = !refSegments.First().StartsWith("#");
-            string externalResource = isExternalResource
-                ? $"{refSegments.First()}/{refSegments[1].TrimEnd('#')}"
-                : null;
+            string externalResource = null;
+            if (isExternalResource)
+            {
+                if (pointer.Contains('#'))
+                {
+                    externalResource = $"{refSegments.First()}/{refSegments[1].TrimEnd('#')}";
+                }
+            }
 
             return (refId, externalResource);
         }

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

@@ -1,15 +1,17 @@
 using System.Collections.Generic;
 using System.Globalization;
 using System.IO;
+using System.Threading.Tasks;
 using FluentAssertions;
 using Microsoft.OpenApi.Extensions;
-using Microsoft.OpenApi.Interfaces;
 using Microsoft.OpenApi.Models;
 using Microsoft.OpenApi.Models.References;
 using Microsoft.OpenApi.Reader;
 using Microsoft.OpenApi.Tests;
 using Microsoft.OpenApi.Writers;
+using Microsoft.OpenApi.Services;
 using Xunit;
+using System.Linq;
 
 namespace Microsoft.OpenApi.Readers.Tests.V31Tests
 {
@@ -392,7 +394,7 @@ public void ParseDocumentsWithReusablePathItemInWebhooksSucceeds()
     new OpenApiDiagnostic() { SpecificationVersion = OpenApiSpecVersion.OpenApi3_1 });
 
             var outputWriter = new StringWriter(CultureInfo.InvariantCulture);
-            var writer = new OpenApiJsonWriter(outputWriter, new() { InlineLocalReferences = true } );
+            var writer = new OpenApiJsonWriter(outputWriter, new() { InlineLocalReferences = true });
             actual.OpenApiDocument.SerializeAsV31(writer);
             var serialized = outputWriter.ToString();
         }
@@ -445,7 +447,7 @@ public void ParseDocumentWithPatternPropertiesInSchemaWorks()
                     }
                 }
             };
-            
+
             // Serialization
             var mediaType = result.OpenApiDocument.Paths["/example"].Operations[OperationType.Get].Responses["200"].Content["application/json"];
 
@@ -461,7 +463,7 @@ public void ParseDocumentWithPatternPropertiesInSchemaWorks()
       type: string
     prop3:
       type: string";
-            
+
             var actualMediaType = mediaType.SerializeAsYaml(OpenApiSpecVersion.OpenApi3_1);
 
             // Assert
@@ -484,5 +486,48 @@ public void ParseDocumentWithReferenceByIdGetsResolved()
             Assert.Equal("object", requestBodySchema.Type);
             Assert.Equal("string", parameterSchema.Type);
         }
+
+        [Fact]
+        public async Task ExternalDocumentDereferenceToOpenApiDocumentUsingJsonPointerWorks()
+        {
+            // Arrange
+            var path = Path.Combine(Directory.GetCurrentDirectory(), SampleFolderPath);
+
+            var settings = new OpenApiReaderSettings
+            {
+                LoadExternalRefs = true,
+                BaseUrl = new(path),
+            };
+
+            // Act
+            var result = await OpenApiDocument.LoadAsync(Path.Combine(SampleFolderPath, "docWithExternalRef.yaml"), settings);
+            var responseSchema = result.OpenApiDocument.Paths["/resource"].Operations[OperationType.Get].Responses["200"].Content["application/json"].Schema;
+
+            // Assert
+            result.OpenApiDocument.Workspace.Contains("./externalResource.yaml");
+            responseSchema.Properties.Count.Should().Be(2); // reference has been resolved
+        }
+
+        [Fact]
+        public async Task ParseExternalDocumentDereferenceToOpenApiDocumentByIdWorks()
+        {
+            // Arrange
+            var path = Path.Combine(Directory.GetCurrentDirectory(), SampleFolderPath);
+
+            var settings = new OpenApiReaderSettings
+            {
+                LoadExternalRefs = true,
+                BaseUrl = new(path),
+            };
+
+            // Act
+            var result = await OpenApiDocument.LoadAsync(Path.Combine(SampleFolderPath, "docWithExternalRef.yaml"), settings);
+            var externalDoc = await OpenApiDocument.LoadAsync(Path.Combine(SampleFolderPath, "externalResource.yaml"), settings);
+
+            var requestBodySchema = result.OpenApiDocument.Paths["/resource"].Operations[OperationType.Get].Parameters.First().Schema;
+
+            // Assert
+            requestBodySchema.Properties.Count.Should().Be(2); // reference has been resolved
+        }
     }
 }

test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiDocument/docWithExternalRef.yaml

@@ -0,0 +1,21 @@
+openapi: 3.1.0
+info:
+  title: ReferenceById
+  version: 1.0.0
+paths:
+  /resource:
+    get:
+      parameters:
+        - name: id
+          in: query
+          required: true
+          schema:
+            $ref: 'https://example.com/schemas/user.json'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: './externalResource.yaml#/components/schemas/todo'
+components: {}

test/Microsoft.OpenApi.Readers.Tests/V31Tests/Samples/OpenApiDocument/externalResource.yaml

@@ -0,0 +1,22 @@
+openapi: 3.1.0
+info:
+  title: ReferencedById
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    todo:
+      type: object
+      properties:
+        id:
+           type: string
+        name:
+           type: string
+    user:
+       $id: 'https://example.com/schemas/user.json'
+       type: object
+       properties:
+         id:
+           type: string
+         name:
+           type: string