feat(schema): resolve $dynamicRef against $dynamicAnchor via OpenApiSchemaReference

aqeelat · aqeelat · commit 06d3b5062cb8 · 2026-06-30T15:59:16.000+03:00
Implements document-scoped $dynamicRef resolution per JSON Schema 2020-12 §8.2.3.2. Bare $dynamicRef schemas (no $ref) now deserialize as OpenApiSchemaReference whose Target resolves via per-document $dynamicAnchor and $anchor registries in OpenApiWorkspace. Resolution order in Target: 1. $dynamicAnchor index (single candidate → resolved automatically) 2. $anchor fallback when zero $dynamicAnchor candidates exist (per §8.2.3.2) 3. null when ambiguous (multiple candidates need dynamic-scope tracking) Anchor registries are populated by recursively walking the entire document tree: component schemas, reusable component definitions (parameters, responses, request bodies, headers, callbacks, path items, media types), inline schemas (paths, operations, webhooks), and all nested subschema locations ($defs, properties, items, allOf, if/then/else, etc.). Public APIs for consumers tracking dynamic scope: - GetDynamicAnchorCandidates(doc, anchorName): returns all candidate schemas - ResolveDynamicAnchorInContext(contextSchema, anchorName): resolves against a specific schema's $defs for context-dependent resolution Other changes: - Deserializer (V31/V32): detect bare $dynamicRef, create OpenApiSchemaReference with IsDynamicRefOnly, parse siblings via ApplySchemaMetadata - JsonSchemaReference: add IsDynamicRefOnly flag, implement IOpenApiSchemaMissingProperties, override SerializeAsV31/V32 for dynamic-only refs - JsonNodeHelper: GetDynamicReferencePointer, ExtractDynamicAnchorName, IsFragmentOnlyDynamicRef - Siblings preserved via ApplySchemaMetadata and surfaced through existing Reference-first property getters Fixes #2911.
diff --git a/src/Microsoft.OpenApi/Models/JsonSchemaReference.cs b/src/Microsoft.OpenApi/Models/JsonSchemaReference.cs
@@ -335,6 +335,13 @@ public class JsonSchemaReference : OpenApiReferenceWithDescription
     /// </summary>
     public IOpenApiSchema? Else { get; set; }
 
+    /// <summary>
+    /// Indicates whether this reference was created from a bare $dynamicRef (no $ref).
+    /// When true, serialization emits $dynamicRef instead of $ref, and Target resolution
+    /// uses the $dynamicAnchor index rather than the $ref URI lookup.
+    /// </summary>
+    internal bool IsDynamicRefOnly { get; set; }
+
     /// <summary>
     /// Parameterless constructor
     /// </summary>
@@ -407,6 +414,36 @@ public JsonSchemaReference(JsonSchemaReference reference) : base(reference)
         If = reference.If;
         Then = reference.Then;
         Else = reference.Else;
+        IsDynamicRefOnly = reference.IsDynamicRefOnly;
+    }
+
+    /// <inheritdoc/>
+    public override void SerializeAsV31(IOpenApiWriter writer)
+    {
+        if (IsDynamicRefOnly)
+        {
+            writer.WriteStartObject();
+            SerializeAdditionalV3XProperties(writer, (w, e) => e.SerializeAsV31(w), base.SerializeAdditionalV31Properties);
+            writer.WriteEndObject();
+        }
+        else
+        {
+            base.SerializeAsV31(writer);
+        }
+    }
+    /// <inheritdoc/>
+    public override void SerializeAsV32(IOpenApiWriter writer)
+    {
+        if (IsDynamicRefOnly)
+        {
+            writer.WriteStartObject();
+            SerializeAdditionalV3XProperties(writer, (w, e) => e.SerializeAsV32(w), base.SerializeAdditionalV32Properties);
+            writer.WriteEndObject();
+        }
+        else
+        {
+            base.SerializeAsV32(writer);
+        }
     }
 
     /// <inheritdoc/>
@@ -419,6 +456,7 @@ protected override void SerializeAdditionalV32Properties(IOpenApiWriter writer)
     {
         SerializeAdditionalV3XProperties(writer, (w, e) => e.SerializeAsV32(w), base.SerializeAdditionalV32Properties);
     }
+
     private void SerializeAdditionalV3XProperties(IOpenApiWriter writer, Action<IOpenApiWriter, IOpenApiSerializable> serializeCallback, Action<IOpenApiWriter> baseSerializer)
     {
         if (Type != ReferenceType.Schema) throw new InvalidOperationException(
diff --git a/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs b/src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs
@@ -35,6 +35,43 @@ private OpenApiSchemaReference(OpenApiSchemaReference schema) : base(schema)
         {
         }
 
+        /// <summary>
+        /// Resolves the target schema. When this reference was created from a bare $dynamicRef,
+        /// resolution first tries the $dynamicAnchor index, then falls back to $anchor resolution
+        /// per JSON Schema 2020-12 §8.2.3.2 / §9.2 (dereferencing). The $anchor fallback only fires
+        /// when there are zero $dynamicAnchor candidates; with multiple candidates the spec requires
+        /// the outermost dynamic anchor, which cannot be computed without dynamic-scope tracking, so
+        /// this returns null. Returns null when neither matches.
+        /// </summary>
+        public override IOpenApiSchema? Target
+        {
+            get
+            {
+                if (Reference.IsDynamicRefOnly)
+                {
+                    var anchorName = Microsoft.OpenApi.Reader.JsonNodeHelper.ExtractDynamicAnchorName(Reference.DynamicRef);
+                    if (!string.IsNullOrEmpty(anchorName)
+                        && Microsoft.OpenApi.Reader.JsonNodeHelper.IsFragmentOnlyDynamicRef(Reference.DynamicRef)
+                        && Reference.HostDocument is { } hostDocument
+                        && hostDocument.Workspace is { } workspace)
+                    {
+                        var candidates = workspace.GetDynamicAnchorCandidates(hostDocument, anchorName!);
+                        if (candidates.Count == 1)
+                            return candidates[0];
+                        // Per §8.2.3.2: when no $dynamicAnchor matches at all, $dynamicRef resolves like $ref
+                        // to the plain-name fragment ($anchor). When multiple $dynamicAnchor candidates exist,
+                        // the spec requires the outermost one, which cannot be computed without dynamic-scope
+                        // tracking, so return null rather than incorrectly falling back to $anchor.
+                        if (candidates.Count == 0
+                            && workspace.ResolveAnchor(hostDocument, anchorName!) is { } anchorTarget)
+                            return anchorTarget;
+                    }
+                    return null;
+                }
+                return base.Target;
+            }
+        }
+
         /// <inheritdoc/>
         public string? Description
         {
diff --git a/src/Microsoft.OpenApi/PublicAPI.Unshipped.txt b/src/Microsoft.OpenApi/PublicAPI.Unshipped.txt
@@ -1 +1,6 @@
 #nullable enable
+override Microsoft.OpenApi.JsonSchemaReference.SerializeAsV31(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
+override Microsoft.OpenApi.JsonSchemaReference.SerializeAsV32(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
+override Microsoft.OpenApi.OpenApiSchemaReference.Target.get -> Microsoft.OpenApi.IOpenApiSchema?
+Microsoft.OpenApi.OpenApiWorkspace.GetDynamicAnchorCandidates(Microsoft.OpenApi.OpenApiDocument! hostDocument, string! anchorName) -> System.Collections.Generic.IReadOnlyList<Microsoft.OpenApi.IOpenApiSchema!>!
+static Microsoft.OpenApi.OpenApiWorkspace.ResolveDynamicAnchorInContext(Microsoft.OpenApi.IOpenApiSchema? contextSchema, string! anchorName) -> Microsoft.OpenApi.IOpenApiSchema?
diff --git a/src/Microsoft.OpenApi/Reader/JsonNodeHelper.cs b/src/Microsoft.OpenApi/Reader/JsonNodeHelper.cs
@@ -167,6 +167,39 @@ public static Dictionary<string, HashSet<T>> CreateArrayMap<T>(this JsonNode? no
             return jsonObject.TryGetPropertyValue("$ref", out var refNode) ? refNode?.GetScalarValue() : null;
         }
 
+        /// <summary>
+        /// Returns the value of $dynamicRef if $ref is absent. Used to create a schema reference
+        /// for bare $dynamicRef schemas (no $ref) so they participate in reference resolution.
+        /// </summary>
+        public static string? GetDynamicReferencePointer(this JsonObject jsonObject)
+        {
+            if (jsonObject.TryGetPropertyValue("$ref", out _))
+                return null;
+            return jsonObject.TryGetPropertyValue("$dynamicRef", out var dynRefNode) ? dynRefNode?.GetScalarValue() : null;
+        }
+
+        /// <summary>
+        /// Extracts the bare anchor name from a $dynamicRef value.
+        /// Handles fragment-only (#meta), absolute-URI (https://example.com#meta), and bare (meta) forms.
+        /// Returns null for null/empty input. Returns empty string for bare "#" (root reference).
+        /// </summary>
+        public static string? ExtractDynamicAnchorName(string? dynamicRef)
+        {
+            if (string.IsNullOrEmpty(dynamicRef)) return null;
+            var hashIndex = dynamicRef!.LastIndexOf('#');
+            return hashIndex >= 0 ? dynamicRef.Substring(hashIndex + 1) : dynamicRef;
+        }
+
+        /// <summary>
+        /// Determines whether a $dynamicRef value is a fragment-only reference (e.g. "#node")
+        /// that targets an anchor within the current document, as opposed to an absolute/relative
+        /// URI reference (e.g. "https://example.com/schema#node") that targets another resource.
+        /// Per JSON Schema 2020-12, only fragment-only dynamic refs resolve against the local
+        /// $dynamicAnchor index; URI-based refs require resolving their target resource first.
+        /// </summary>
+        public static bool IsFragmentOnlyDynamicRef(string? dynamicRef)
+            => !string.IsNullOrEmpty(dynamicRef) && dynamicRef![0] == '#';
+
         public static string? GetJsonSchemaIdentifier(this JsonObject jsonObject)
         {
             return jsonObject.TryGetPropertyValue("$id", out var idNode) ? idNode?.GetScalarValue() : null;
diff --git a/src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs b/src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs
@@ -444,6 +444,7 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
         var jsonObject = node.CheckMapNode(OpenApiConstants.Schema, context);
 
         var pointer = jsonObject.GetReferencePointer();
+        var dynamicPointer = jsonObject.GetDynamicReferencePointer();
         var identifier = jsonObject.GetJsonSchemaIdentifier();
 
         if (pointer != null)
@@ -467,6 +468,27 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
             return result;
         }
 
+        if (dynamicPointer != null)
+        {
+            var nodeLocation = context.GetLocation();
+            var anchorName = JsonNodeHelper.ExtractDynamicAnchorName(dynamicPointer);
+            var result = new OpenApiSchemaReference(!string.IsNullOrEmpty(anchorName) ? anchorName! : dynamicPointer, hostDocument);
+            var referenceMetadata = new OpenApiSchema();
+            jsonObject.ParseMap(referenceMetadata, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument, context,
+                static (schema, name, value) =>
+                {
+                    if (!string.Equals(name, OpenApiConstants.DynamicRef, StringComparison.Ordinal))
+                    {
+                        schema.UnrecognizedKeywords ??= new Dictionary<string, JsonNode>(StringComparer.Ordinal);
+                        schema.UnrecognizedKeywords[name] = value;
+                    }
+                });
+            result.Reference.ApplySchemaMetadata(referenceMetadata, jsonObject);
+            result.Reference.SetJsonPointerPath(dynamicPointer, nodeLocation);
+            result.Reference.IsDynamicRefOnly = true;
+            return result;
+        }
+
         var schema = new OpenApiSchema();
 
         jsonObject.ParseMap(schema, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument, context,
diff --git a/src/Microsoft.OpenApi/Reader/V32/OpenApiSchemaDeserializer.cs b/src/Microsoft.OpenApi/Reader/V32/OpenApiSchemaDeserializer.cs
@@ -444,6 +444,7 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
         var jsonObject = node.CheckMapNode(OpenApiConstants.Schema, context);
 
         var pointer = jsonObject.GetReferencePointer();
+        var dynamicPointer = jsonObject.GetDynamicReferencePointer();
         var identifier = jsonObject.GetJsonSchemaIdentifier();
 
         if (pointer != null)
@@ -467,6 +468,27 @@ public static IOpenApiSchema LoadSchema(JsonNode node, OpenApiDocument hostDocum
             return result;
         }
 
+        if (dynamicPointer != null)
+        {
+            var nodeLocation = context.GetLocation();
+            var anchorName = JsonNodeHelper.ExtractDynamicAnchorName(dynamicPointer);
+            var result = new OpenApiSchemaReference(!string.IsNullOrEmpty(anchorName) ? anchorName! : dynamicPointer, hostDocument);
+            var referenceMetadata = new OpenApiSchema();
+            jsonObject.ParseMap(referenceMetadata, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument, context,
+                static (schema, name, value) =>
+                {
+                    if (!string.Equals(name, OpenApiConstants.DynamicRef, StringComparison.Ordinal))
+                    {
+                        schema.UnrecognizedKeywords ??= new Dictionary<string, JsonNode>(StringComparer.Ordinal);
+                        schema.UnrecognizedKeywords[name] = value;
+                    }
+                });
+            result.Reference.ApplySchemaMetadata(referenceMetadata, jsonObject);
+            result.Reference.SetJsonPointerPath(dynamicPointer, nodeLocation);
+            result.Reference.IsDynamicRefOnly = true;
+            return result;
+        }
+
         var schema = new OpenApiSchema();
 
         jsonObject.ParseMap(schema, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument, context,
diff --git a/src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs b/src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDynamicRefTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDynamicRefTests.cs
diff --git a/test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiDynamicRefTests.cs b/test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiDynamicRefTests.cs
