fix: add $schema sibling preservation and fix $defs location tracking

Add $schema dialect URI as a sibling override on JsonSchemaReference,
matching the pattern used for the other JSON Schema 2020-12 keywords.

Also fix the $defs parsing loop in V31/V32 LoadSchema to push/pop
the parsing context location stack (context.StartObject/EndObject)
around each LoadSchema call, mirroring JsonNodeHelper.CreateMap.
Without this, nested schemas inside a reference's $defs get
incorrect nodeLocation values, breaking relative $ref resolution
and source-pointer diagnostics.

Adds a scalar round-trip test covering $id, $schema, $comment,
$anchor, $dynamicRef serialization.

Ref: #2895

Author: aqeelat

src/Microsoft.OpenApi/Models/JsonSchemaReference.cs

@@ -64,6 +64,11 @@ public class JsonSchemaReference : OpenApiReferenceWithDescription
     /// </summary>
     public string? SchemaId { get; set; }
 
+    /// <summary>
+    /// The $schema dialect URI which by default SHOULD override that of the referenced component.
+    /// </summary>
+    public Uri? Schema { get; set; }
+
     /// <summary>
     /// A $comment which by default SHOULD override that of the referenced component.
     /// </summary>
@@ -113,6 +118,7 @@ public JsonSchemaReference(JsonSchemaReference reference) : base(reference)
         Examples = reference.Examples;
         Extensions = reference.Extensions != null ? new Dictionary<string, IOpenApiExtension>(reference.Extensions) : null;
         SchemaId = reference.SchemaId;
+        Schema = reference.Schema;
         Comment = reference.Comment;
         Vocabulary = reference.Vocabulary != null ? new Dictionary<string, bool>(reference.Vocabulary) : null;
         DynamicRef = reference.DynamicRef;
@@ -140,6 +146,7 @@ private void SerializeAdditionalV3XProperties(IOpenApiWriter writer, OpenApiSpec
 
         // JSON Schema 2020-12 keyword siblings (preserved per OAS 3.1+ / JSON Schema 2020-12 semantics)
         writer.WriteProperty(OpenApiConstants.Id, SchemaId);
+        writer.WriteProperty(OpenApiConstants.DollarSchema, Schema?.ToString());
         writer.WriteProperty(OpenApiConstants.Comment, Comment);
         writer.WriteOptionalMap(OpenApiConstants.Vocabulary, Vocabulary, (w, s) => w.WriteValue(s));
         if (version == OpenApiSpecVersion.OpenApi3_1)
@@ -233,6 +240,12 @@ protected override void SetAdditional31MetadataFromMapNode(JsonObject jsonObject
             SchemaId = id;
         }
 
+        var schemaValue = GetPropertyValueFromNode(jsonObject, OpenApiConstants.DollarSchema);
+        if (!string.IsNullOrEmpty(schemaValue) && Uri.TryCreate(schemaValue, UriKind.Absolute, out var schemaUri))
+        {
+            Schema = schemaUri;
+        }
+
         var comment = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Comment);
         if (!string.IsNullOrEmpty(comment))
         {

src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs

@@ -49,7 +49,7 @@ public string? Title
             set => Reference.Title = value;
         }
         /// <inheritdoc/>
-        public Uri? Schema { get => Target?.Schema; }
+        public Uri? Schema { get => Reference.Schema ?? Target?.Schema; }
         /// <inheritdoc/>
         public string? Id { get => string.IsNullOrEmpty(Reference.SchemaId) ? Target?.Id : Reference.SchemaId; }
         /// <inheritdoc/>

src/Microsoft.OpenApi/PublicAPI.Unshipped.txt

@@ -9,6 +9,8 @@ Microsoft.OpenApi.JsonSchemaReference.DynamicAnchor.get -> string?
 Microsoft.OpenApi.JsonSchemaReference.DynamicAnchor.set -> void
 Microsoft.OpenApi.JsonSchemaReference.DynamicRef.get -> string?
 Microsoft.OpenApi.JsonSchemaReference.DynamicRef.set -> void
+Microsoft.OpenApi.JsonSchemaReference.Schema.get -> System.Uri?
+Microsoft.OpenApi.JsonSchemaReference.Schema.set -> void
 Microsoft.OpenApi.JsonSchemaReference.SchemaId.get -> string?
 Microsoft.OpenApi.JsonSchemaReference.SchemaId.set -> void
 Microsoft.OpenApi.JsonSchemaReference.Vocabulary.get -> System.Collections.Generic.IDictionary<string!, bool>?

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

@@ -460,10 +460,16 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
                 var defs = new Dictionary<string, IOpenApiSchema>(StringComparer.Ordinal);
                 foreach (var kvp in defsObj)
                 {
-                    if (kvp.Value is not null)
+                    if (kvp.Value is null) continue;
+                    context.StartObject(kvp.Key);
+                    try
                     {
                         defs[kvp.Key] = LoadSchema(kvp.Value, hostDocument, context);
                     }
+                    finally
+                    {
+                        context.EndObject();
+                    }
                 }
                 result.Reference.Definitions = defs;
             }

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

@@ -460,10 +460,16 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
                 var defs = new Dictionary<string, IOpenApiSchema>(StringComparer.Ordinal);
                 foreach (var kvp in defsObj)
                 {
-                    if (kvp.Value is not null)
+                    if (kvp.Value is null) continue;
+                    context.StartObject(kvp.Key);
+                    try
                     {
                         defs[kvp.Key] = LoadSchema(kvp.Value, hostDocument, context);
                     }
+                    finally
+                    {
+                        context.EndObject();
+                    }
                 }
                 result.Reference.Definitions = defs;
             }

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

@@ -1039,6 +1039,7 @@ public async Task ParseSchemaReferencePreservesScalarKeywordSiblings()
                     Referencing:
                       $ref: '#/components/schemas/Target'
                       $id: 'https://example.com/referencing.json'
+                      $schema: 'https://json-schema.org/draft/2020-12/schema'
                       $comment: A comment sibling
                       $anchor: myAnchor
                       $dynamicRef: '#myAnchor'
@@ -1052,6 +1053,50 @@ public async Task ParseSchemaReferencePreservesScalarKeywordSiblings()
             // Assert
             referencing.Should().BeOfType<OpenApiSchemaReference>();
             referencing.Id.Should().Be("https://example.com/referencing.json");
+            referencing.Schema.Should().Be(new Uri("https://json-schema.org/draft/2020-12/schema"));
+            referencing.Comment.Should().Be("A comment sibling");
+            ((IOpenApiSchemaMissingProperties)referencing).Anchor.Should().Be("myAnchor");
+            referencing.DynamicRef.Should().Be("#myAnchor");
+        }
+
+        [Fact]
+        public async Task SerializeSchemaReferencePreservesScalarKeywordSiblings()
+        {
+            // Arrange
+            var yaml = """
+                openapi: 3.1.0
+                info:
+                  title: Scalar round-trip
+                  version: 1.0.0
+                paths: {}
+                components:
+                  schemas:
+                    Target:
+                      type: object
+                    Referencing:
+                      $ref: '#/components/schemas/Target'
+                      $id: 'https://example.com/referencing.json'
+                      $schema: 'https://json-schema.org/draft/2020-12/schema'
+                      $comment: A comment sibling
+                      $anchor: myAnchor
+                      $dynamicRef: '#myAnchor'
+                """;
+
+            // Act — parse then serialize back
+            using var stream = new MemoryStream(System.Text.Encoding.UTF8.GetBytes(yaml));
+            var result = await OpenApiDocument.LoadAsync(stream, "yaml", SettingsFixture.ReaderSettings);
+            var writer = new StringWriter();
+            result.Document.SerializeAsV31(new OpenApiYamlWriter(writer));
+            var output = writer.ToString();
+
+            // Assert — round-trip preserves scalar siblings alongside $ref
+            using var roundTripStream = new MemoryStream(System.Text.Encoding.UTF8.GetBytes(output));
+            var roundTripResult = await OpenApiDocument.LoadAsync(roundTripStream, "yaml", SettingsFixture.ReaderSettings);
+            var referencing = roundTripResult.Document.Components!.Schemas["Referencing"];
+
+            referencing.Should().BeOfType<OpenApiSchemaReference>();
+            referencing.Id.Should().Be("https://example.com/referencing.json");
+            referencing.Schema.Should().Be(new Uri("https://json-schema.org/draft/2020-12/schema"));
             referencing.Comment.Should().Be("A comment sibling");
             ((IOpenApiSchemaMissingProperties)referencing).Anchor.Should().Be("myAnchor");
             referencing.DynamicRef.Should().Be("#myAnchor");