feat(schema): resolve bare $dynamicRef via $dynamicAnchor index

[aqeelat]

Pull Request

Description

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 resolves automatically
2. $anchor fallback — when zero $dynamicAnchor candidates exist (per §8.2.3.2)
3. null — when ambiguous (multiple candidates need dynamic-scope tracking)

Type of Change

• New feature (non-breaking change which adds functionality)

Public APIs for consumers tracking dynamic scope

• GetDynamicAnchorCandidates(doc, anchorName) — returns all candidate schemas
• ResolveDynamicAnchorInContext(contextSchema, anchorName) — resolves against a specific schema's $defs

$ref sibling behavior

This PR relies on the existing OpenAPI.NET 3.1/3.2 behavior where $ref schema siblings are preserved on JsonSchemaReference and surfaced through OpenApiSchemaReference's existing reference-first property getters.

This PR does not introduce that behavior. It extends the same storage model to bare $dynamicRef schemas so sibling keywords are preserved while the schema participates in reference resolution.

See #2919 for a broader discussion on whether the reference-first getter model should be revised for assertion keywords.

Anchor index coverage

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.).

Open question

When multiple schemas declare the same $dynamicAnchor, Target returns null (ambiguous). The spec requires the outermost candidate in the dynamic evaluation scope. Automatic resolution would require threading evaluation context through Target (e.g., AsyncLocal<Stack>). Currently consumers handle this via GetDynamicAnchorCandidates + ResolveDynamicAnchorInContext. Feedback welcome on whether the library should handle this automatically or leave it to consumers.

Testing

• Unit tests added/updated
• All existing tests pass (except 7 pre-existing Serialize_DoesNotMutateDom failures on clean main)

46 dynamic-ref tests across V31 and V32 covering: bare $dynamicRef deserialization, resolution to anchors in all schema locations, ambiguity handling, $anchor fallback, $dynamicAnchor precedence, round-trip serialization, sibling preservation, context-aware resolution, OM-built document, and $ref regression.

Microsoft.OpenApi.Tests: 1149 passed. Microsoft.OpenApi.Readers.Tests: 535 passed, 7 pre-existing failures.

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Versions applicability

• My change applies to the version 3.X of the library, if so PR link: (this PR)

Related

• Fixes Feature: Resolve $dynamicRef against $dynamicAnchor in the schema reference resolution pipeline #2911
• Builds on fix: preserve JSON Schema 2020-12 keyword siblings on $ref schemas for OAS 3.1+ #2896 (preserve JSON Schema 2020-12 keyword siblings on $ref schemas)
• feat: resolve $dynamicRef against $dynamicAnchor for recursive types kiota#7817 tracks the consumer-side use case

[aqeelat]

@baywet sorry for the mega PR. Most of the changes are tests and mechanical changes. However, if you want, I can split it into multiple PRs if that will make it easier for you to review.

[baywet]

Thanks for the contribution!

No worries, I'll take the time to review during the week.

Looking back at the reference mechanisms that are implemented throughout the library, I realized we had a specification/documentation page that never got published on release. Took the time to clean it up a little and it's now available here.

https://learn.microsoft.com/en-us/openapi/openapi.net/references-openapi

Let us know what you think!

[Copilot]

Pull request overview

This PR adds document-scoped $dynamicRef resolution for OpenAPI 3.1/3.2 JSON Schema 2020-12 by indexing $dynamicAnchor/$anchor declarations per OpenApiDocument in OpenApiWorkspace, and by deserializing bare $dynamicRef schemas as OpenApiSchemaReference so they participate in the existing reference-resolution pipeline.

Changes:

• Index $dynamicAnchor and $anchor declarations per document in OpenApiWorkspace and expose APIs for candidate lookup + context-aware resolution.
• Update V31/V32 schema deserializers to create an OpenApiSchemaReference for bare $dynamicRef (no $ref) and preserve siblings via ApplySchemaMetadata.
• Add extensive V31/V32 unit tests covering registration, resolution precedence, ambiguity behavior, serialization round-trips, and tricky schema-bearing locations (responses/headers/callback cycles/etc.).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiDynamicRefTests.cs	Adds OpenAPI 3.2 test coverage for bare $dynamicRef deserialization, resolution, anchor registration across OAS locations, and serialization behavior.
test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiDynamicRefTests.cs	Adds OpenAPI 3.1 test coverage for anchor indexing across subschema locations, ambiguity behavior, context-aware resolution, and $ref regression scenarios.
src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs	Implements per-document $dynamicAnchor/$anchor registries and recursive anchor discovery across components + inline paths/webhooks/callback graphs.
src/Microsoft.OpenApi/Reader/V32/OpenApiSchemaDeserializer.cs	Deserializes bare $dynamicRef schemas into OpenApiSchemaReference and applies schema metadata so siblings are preserved.
src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs	Same as V32, for OpenAPI 3.1 schema deserialization.
src/Microsoft.OpenApi/Reader/JsonNodeHelper.cs	Adds $dynamicRef pointer detection and helper methods for extracting anchor names + determining fragment-only refs.
src/Microsoft.OpenApi/PublicAPI.Unshipped.txt	Records new/changed public API surface for serialization overrides, Target override, and new workspace APIs.
src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs	Overrides Target to resolve bare $dynamicRef via workspace $dynamicAnchor index with $anchor fallback when appropriate.
src/Microsoft.OpenApi/Models/JsonSchemaReference.cs	Adds IsDynamicRefOnly and custom serialization behavior to emit $dynamicRef (without $ref) for dynamic-ref-only references, plus interface updates for anchor walking.

[baywet]

Thanks for the contribution!

In addition to the comments I've left, I think we have good coverage of the deserialization scenarios, and some coverage of the serialization scenarios (at least for basic properties).
In think that one key aspect that is missing from the tests is: people using the object model to build documents. For "regular refs" components registration is required. I'd like to see more tests demonstrating that a document built from OM can resolve dynamic refs without requiring a re-parsing.

[aqeelat]

@baywet CodeQL is suggesting we convert the foreach + if (x is not null) patterns in OpenApiWorkspace to .Where() and FirstOrDefault. The trade-off: .Where() reads cleaner but allocates an iterator per call site; foreach + if iterates directly with zero allocations. Negligible in a one-time registration path like RegisterComponents. Should we convert for readability or keep as-is?

[baywet]

@baywet CodeQL is suggesting we convert the foreach + if (x is not null) patterns in OpenApiWorkspace to .Where() and FirstOrDefault. The trade-off: .Where() reads cleaner but allocates an iterator per call site; foreach + if iterates directly with zero allocations. Negligible in a one-time registration path like RegisterComponents. Should we convert for readability or keep as-is?

Let's convert for consistency (we have patterns like those throughout the codebase). Allocation wise, the costliest part is the DOM itself and associated strings, the iterators are short lived and negligeable in comparison. And we've made significant performance improvements over the past year or so to have a better margin here.

[aqeelat]

Done. Converted all foreach + if (x is not null) patterns to .Where() throughout OpenApiWorkspace.cs, and replaced the ResolveDynamicAnchorInContext loop with FirstOrDefault. Pushed in the latest force-push.

All review comments should be addressed now. Do you think this can be merged today?

[aqeelat]

@copilot fix failing test and address the other review items

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

[baywet]

copilot fix failing test and address the other review items

@aqueelat, I believe this doesn't work on forks. (I had the same problem with aspnetcore recently)

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 9 comments.

[baywet]

@aqeelat merging #2918 means this one is conflicting now. Would you mind solving the conflicts before I give it another look please?

[aqeelat]

@baywet Conflicts resolved — rebased on origin/main.

One observation from the merge: RegisterSchemaIdentifiers (#2918) and RegisterAnchors (this PR) both recursively walk the same schema tree for each component schema — once to register $id/$anchor as component URIs, once to register $dynamicAnchor/$anchor in the anchor registry. The walks visit the same nodes but serve different registries with different reference-handling strategies (RegisterSchemaIdentifiers skips references; RegisterAnchors reads from the JsonSchemaReference directly).

I left them as separate calls for now. Merging into one pass would require:

• Adding a document parameter to all RegisterSchemaIdentifiers overloads
• Adding reference-specific anchor registration before the existing OpenApiSchemaReference skip
• Adding reference-specific child enumeration via a separate EnumerateChildren(JsonSchemaReference) overload (since JsonSchemaReference is not IOpenApiSchema)

Happy to do that if you prefer a single walk, or leave as-is since the double walk is O(2n) and doesn't show up in benchmarks.

[baywet]

@aqeelat thanks for handling the conflicts, and for pointing this out. Let's merge the crawling, it should reduce the amount of code we have and improve the performance.

[aqeelat]

@baywet can we do it in a different PR?

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 3 comments.

[aqeelat]

@baywet I forgot to mention that I already did the merged crawl in 77c976c

I have another PR to work on to address #2913 (comment). I'll stack it on top of this one.

The kiota changes are ready locally but require we release a new version with this PR.

[baywet]

Thank you for making the changes!

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated 2 comments.

[aqeelat]

@baywet I just pushed the copilot review fixes.

I also noticed there are a couple of tests not mirrored between V31 and V32. I will include them in the next PR.