fix: preserve JSON Schema 2020-12 keyword siblings on $ref schemas for OAS 3.1+ by aqeelat · Pull Request #2896 · microsoft/OpenAPI.NET

aqeelat · 2026-06-19T17:52:53Z

Problem

OpenApiV31Deserializer.LoadSchema short-circuits on $ref before ParseMap, so JSON Schema 2020-12 keyword siblings ($defs, $dynamicAnchor, $dynamicRef, $id, $schema, $anchor, $vocabulary, $comment) were never parsed into the object model. This made Pattern B (generic template + $dynamicRef binding via sibling $defs) unimplementable for any tool built on Microsoft.OpenApi.

Fixes #2895.

Solution

Mirrors the #2369 annotation-sibling pattern across four coordinated changes:

Parser extraction — SetAdditional31MetadataFromMapNode extracts scalar/collection siblings; $defs is parsed in LoadSchema (needs LoadSchema for nested schema materialization).
Storage — 8 new properties on JsonSchemaReference ($id stored as SchemaId to avoid collision with BaseOpenApiReference.Id).
Accessor overrides — OpenApiSchemaReference getters changed from Target?.X to Reference.X ?? Target?.X.
Serialization — SerializeAdditionalV3XProperties emits the new siblings alongside $ref.

Version-safe by call-site separation: SetAdditional31MetadataFromMapNode is only reachable from V31/V32 LoadSchema, never V3. All 1639 existing tests pass unchanged.

Scope

Intentionally narrow — only JSON Schema 2020-12 structural keywords ($-prefixed). Application keywords (type, properties, required, etc.) still delegate to Target. Full sibling compliance is a separate concern with backward-compat implications.

Empty $defs: {} / $vocabulary: {} siblings do not suppress the target's values (collection assigned only when non-empty).

Test coverage

12 new tests across V31 and V32:

Parse: keyword siblings ($dynamicAnchor + $defs), scalar siblings ($id, $schema, $comment, $anchor, $dynamicRef), $vocabulary, allOf-binding variant
Serialize round-trip: keyword siblings + scalar siblings

…r OAS 3.1+ OpenApiV31Deserializer.LoadSchema short-circuits on $ref before ParseMap, so sibling keywords ($defs, $dynamicAnchor, $dynamicRef, $id, $anchor, $vocabulary, $comment) were never parsed into the object model. This made Pattern B (generic template + binding) unimplementable for any tool built on Microsoft.OpenApi. The fix mirrors the microsoft#2369 annotation-sibling pattern across four coordinated changes: - Parser extraction in SetAdditional31MetadataFromMapNode (scalars + $vocabulary) and LoadSchema ($defs, which needs LoadSchema for nested schema materialization) - Storage: 7 new properties on JsonSchemaReference - Accessor overrides on OpenApiSchemaReference (Reference.X ?? Target?.X) - Serialization in SerializeAdditionalV3XProperties Version-safe by call-site separation: SetAdditional31MetadataFromMapNode is only reachable from V31/V32 LoadSchema, never V3. Ref: microsoft#2895

Switch from GetPropertyValueFromNode(...) ?? X to the if (!string.IsNullOrEmpty(...)) pattern used by the existing Title/annotation extraction, for reviewer consistency. Also add test for the allOf-based binding variant where $defs sits inside allOf[0] and the nested schema has $ref + $dynamicAnchor (the pattern from the blocker analysis). Ref: microsoft#2895

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: microsoft#2895

Mirrors the 6 V31 sibling preservation tests in V32Tests, using SerializeAsV32 for the round-trip tests. Parse tests are identical since both versions share the same LoadSchema + SetAdditional31MetadataFromMapNode path. Ref: microsoft#2895

An empty $defs: {} or $vocabulary: {} sibling would assign an empty collection to the reference, blocking fallthrough to Target via the ?? coalescing getter. Only assign when the collection has entries. Ref: microsoft#2895

aqeelat · 2026-06-19T17:54:16Z

@microsoft-github-policy-service agree

…bulary round-trip tests - Empty $defs: {} / $vocabulary: {} must fall through to Target (guards the .Count > 0 fix in commit 4666f2c) - 3.0 document with $ref + siblings must drop siblings per spec (guards the version-safety guarantee) - $vocabulary round-trip (parse -> serialize -> parse) Ref: microsoft#2895

…nstructor Achieves 100% diff coverage on all changed files. Ref: microsoft#2895

Copilot

Pull request overview

This PR fixes OpenAPI 3.1+ schema $ref handling so JSON Schema 2020-12 keyword siblings (notably $defs, $dynamicAnchor, $dynamicRef, $id, $schema, $anchor, $vocabulary, $comment) are preserved on OpenApiSchemaReference instances during parsing and are emitted during serialization, enabling downstream tooling to implement dynamic-scope patterns.

Changes:

Extend JsonSchemaReference and OpenApiSchemaReference to store and surface JSON Schema 2020-12 keyword siblings on $ref schemas (with reference-first accessor precedence).
Update V3.1/V3.2 schema deserializers to parse $defs siblings even when $ref short-circuits.
Add V3.1 and V3.2 reader/round-trip tests covering parsing, serialization, and edge cases (including empty sibling collections and 3.0 safety).

Reviewed changes

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

Show a summary per file

File	Description
test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiSchemaTests.cs	Adds V3.1 parsing/serialization tests ensuring `$ref` keyword siblings are preserved and 3.0 behavior remains unchanged.
test/Microsoft.OpenApi.Readers.Tests/V32Tests/OpenApiSchemaTests.cs	Adds V3.2 parsing/serialization tests ensuring `$ref` keyword siblings are preserved.
src/Microsoft.OpenApi/Reader/V31/OpenApiSchemaDeserializer.cs	Parses `$defs` siblings for `$ref` schemas in the V3.1 reader path.
src/Microsoft.OpenApi/Reader/V32/OpenApiSchemaDeserializer.cs	Parses `$defs` siblings for `$ref` schemas in the V3.2 reader path.
src/Microsoft.OpenApi/PublicAPI.Unshipped.txt	Declares newly added `JsonSchemaReference` public surface area.
src/Microsoft.OpenApi/Models/References/OpenApiSchemaReference.cs	Updates getters to prefer sibling keyword values stored on the reference over the target schema.
src/Microsoft.OpenApi/Models/JsonSchemaReference.cs	Adds storage, parsing, copying, and serialization for JSON Schema 2020-12 keyword siblings on schema references.

+            // Parse $defs sibling — requires LoadSchema for nested schema materialization,
+            // so it cannot be done inside SetAdditional31MetadataFromMapNode.
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.Defs, out var defsNode) && defsNode is JsonObject defsObj)
+            {
+                var defs = new Dictionary<string, IOpenApiSchema>(StringComparer.Ordinal);
+                foreach (var kvp in defsObj)
+                {
+                    if (kvp.Value is null) continue;
+                    context.StartObject(kvp.Key);
+                    try
+                    {
+                        defs[kvp.Key] = LoadSchema(kvp.Value, hostDocument, context);
+                    }
+                    finally
+                    {
+                        context.EndObject();
+                    }
+                }
+                if (defs.Count > 0)
+                {
+                    result.Reference.Definitions = defs;
+                }
+            }


+            // Parse $defs sibling — requires LoadSchema for nested schema materialization,
+            // so it cannot be done inside SetAdditional31MetadataFromMapNode.
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.Defs, out var defsNode) && defsNode is JsonObject defsObj)
+            {
+                var defs = new Dictionary<string, IOpenApiSchema>(StringComparer.Ordinal);
+                foreach (var kvp in defsObj)
+                {
+                    if (kvp.Value is null) continue;
+                    context.StartObject(kvp.Key);
+                    try
+                    {
+                        defs[kvp.Key] = LoadSchema(kvp.Value, hostDocument, context);
+                    }
+                    finally
+                    {
+                        context.EndObject();
+                    }
+                }
+                if (defs.Count > 0)
+                {
+                    result.Reference.Definitions = defs;
+                }
+            }


        // Additional schema metadata annotations in 3.1
        writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
        writer.WriteProperty(OpenApiConstants.Title, Title);


baywet

Thanks for the contribution!
A couple of comments to help this move forward

baywet · 2026-06-22T12:26:02Z

+        if (version == OpenApiSpecVersion.OpenApi3_1)
+        {
+            writer.WriteOptionalMap(OpenApiConstants.Defs, Definitions, (w, s) => s.SerializeAsV31(w));
+        }
+        else
+        {
+            writer.WriteOptionalMap(OpenApiConstants.Defs, Definitions, (w, s) => s.SerializeAsV32(w));
+        }


why do you need to use the version instead of the callback?
this is brittle and we might forget to update things here in future versions

baywet · 2026-06-22T12:28:56Z

+
+            // Parse $defs sibling — requires LoadSchema for nested schema materialization,
+            // so it cannot be done inside SetAdditional31MetadataFromMapNode.
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.Defs, out var defsNode) && defsNode is JsonObject defsObj)


we could refactor that to accept a callback. Assuming the SetMetadata method is internal

baywet · 2026-06-22T12:29:51Z

+            referencing.Should().BeOfType<OpenApiSchemaReference>();
+            referencing.Description.Should().Be("Sibling description");
+            referencing.DynamicAnchor.Should().Be("anchor");
+            referencing.Definitions.Should().NotBeNull();
+            referencing.Definitions!.Should().ContainKey("sibling");
+            referencing.Definitions["sibling"].DynamicAnchor.Should().Be("inner");


refactor to use the assert and not the fluent API. Long term we should get rid of this library.

baywet · 2026-06-22T12:56:56Z

+Microsoft.OpenApi.JsonSchemaReference.Anchor.get -> string?
+Microsoft.OpenApi.JsonSchemaReference.Anchor.set -> void
+Microsoft.OpenApi.JsonSchemaReference.Comment.get -> string?
+Microsoft.OpenApi.JsonSchemaReference.Comment.set -> void
+Microsoft.OpenApi.JsonSchemaReference.Definitions.get -> System.Collections.Generic.IDictionary<string!, Microsoft.OpenApi.IOpenApiSchema!>?
+Microsoft.OpenApi.JsonSchemaReference.Definitions.set -> void
+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>?


In JSON schema 2020-12 only annotation keywords are allowed next to $ref.
$anchor, $dynamicRef, $dynamicAnchor, $defs, $schema $id and $vocabulary are all core vocabulary keywords.
The only exception is $comment that's technically core vocabulary but allowed anyway.
The only fields that implement this behaviour (target vs reference value) are the annotation keywords (default, readOnly....)

Let me know if you have any additional comments or questions.

Actually, after digging some more, it seems that:

$defs is allowed next two $ref for the whole thing to work

so is $id

so is $schema

I couldn't find any additional evidence for $anchor, $dynamicAnchor or $vocabulary

actually I went ahead and had additional discussions with both @handrews and @darrelmiller (thank you both). My understanding was wrong.
Any JSON Schema keyword can appear next to $ref, some might not be applicable (not do anything) due to their nature, some might be contradictory when appearing both in the reference and the referenced schema, in which case, it's up to the application to define what the behaviour should be.

In the case where both are present, we have a precedent of returning the reference value for annotation keywords, so being consistent here makes sense. Then the application can check the reference and the target values, and compare them, if the difference is important to the application.

Any keyword in JSON schema exposed as a property in the IOpenAPISchema interface as well as in the IOpenApiSchemaMissingProperties should have:

a corresponding setter in the JsonSchemaReference type, and serialization code to match (use x-jsonschema prefix for OAI < 3.1)

a corresponding getter in the JsonSchemaReference type, and the deserialization code to match (use x-jsonschema prefix for OAI < 3.1)

a corresponding setter in OpenApiSchemaReference, that maps to the reference corresponding setter

a corresponding getter, which returns the reference value when present, otherwise the target value

cloning and unit test code like you've started

Now, I understand this is significant work, if you want to focus on the properties you've identified first, and punt the other properties to an additional issue, let me know.

aqeelat added 5 commits June 19, 2026 18:33

aqeelat requested a review from a team as a code owner June 19, 2026 17:52

aqeelat added 2 commits June 19, 2026 20:58

test: add CreateShallowCopy test to cover JsonSchemaReference copy co…

af0686a

…nstructor Achieves 100% diff coverage on all changed files. Ref: microsoft#2895

baywet requested a review from Copilot June 22, 2026 12:24

Copilot started reviewing on behalf of baywet June 22, 2026 12:26 View session

Copilot AI reviewed Jun 22, 2026

View reviewed changes

baywet requested changes Jun 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: preserve JSON Schema 2020-12 keyword siblings on $ref schemas for OAS 3.1+#2896

fix: preserve JSON Schema 2020-12 keyword siblings on $ref schemas for OAS 3.1+#2896
aqeelat wants to merge 7 commits into
microsoft:mainfrom
aqeelat:fix/preserve-ref-siblings-oas31

aqeelat commented Jun 19, 2026

Uh oh!

aqeelat commented Jun 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

baywet left a comment

Uh oh!

baywet Jun 22, 2026

Uh oh!

baywet Jun 22, 2026

Uh oh!

baywet Jun 22, 2026

Uh oh!

baywet Jun 22, 2026

Uh oh!

baywet Jun 22, 2026

Uh oh!

baywet Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

aqeelat commented Jun 19, 2026

Problem

Solution

Scope

Test coverage

Uh oh!

aqeelat commented Jun 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

baywet left a comment

Choose a reason for hiding this comment

Uh oh!

baywet Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

baywet Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants