Add JSON Schema 2020-12 metadata annotations to OpenApiSchemaReference

global.json

@@ -1,5 +1,5 @@
 {
   "sdk": {
-    "version": "8.0.406"
+    "version": "8.0.115"
   }
 }

src/Microsoft.OpenApi/Models/OpenApiDocument.cs

@@ -589,7 +589,7 @@ private static string ConvertByteArrayToString(byte[] hash)
                     // Enables setting the complete JSON path for nested subschemas e.g. #/components/schemas/person/properties/address
                     if (useExternal)
                     {
-                        var relPathSegment = referenceV3.Split(['#'], StringSplitOptions.RemoveEmptyEntries)[1];
+                        var relPathSegment = referenceV3.Split(new char[] {'#'}, StringSplitOptions.RemoveEmptyEntries)[1];
                         relativePath = $"#{relPathSegment}";
                     }
                     else
@@ -625,7 +625,7 @@ private static bool IsSubComponent(string reference)
 
             if (fragment.StartsWith("/components/schemas/", StringComparison.OrdinalIgnoreCase))
             {
-                var segments = fragment.Split(['/'], StringSplitOptions.RemoveEmptyEntries);
+                var segments = fragment.Split(new char[] {'/'}, StringSplitOptions.RemoveEmptyEntries);
 
                 // Expect exactly 3 segments for root-level schema: ["components", "schemas", "person"]
                 // Anything longer means it's a subcomponent.

src/Microsoft.OpenApi/Models/OpenApiReference.cs

@@ -2,6 +2,7 @@
 // Licensed under the MIT license.
 
 using System;
+using System.Collections.Generic;
 using System.Linq;
 using System.Text.Json.Nodes;
 using Microsoft.OpenApi.Reader;
@@ -26,6 +27,42 @@ public class OpenApiReference : IOpenApiSerializable, IOpenApiDescribedElement,
         /// </summary>
         public string? Description { get; set; }
 
+        /// <summary>
+        /// A default value which by default SHOULD override that of the referenced component.
+        /// If the referenced object-type does not allow a default field, then this field has no effect.
+        /// </summary>
+        public JsonNode? Default { get; set; }
+
+        /// <summary>
+        /// A title which by default SHOULD override that of the referenced component.
+        /// If the referenced object-type does not allow a title field, then this field has no effect.
+        /// </summary>
+        public string? Title { get; set; }
+
+        /// <summary>
+        /// Indicates whether the referenced component is deprecated.
+        /// If the referenced object-type does not allow a deprecated field, then this field has no effect.
+        /// </summary>
+        public bool? Deprecated { get; set; }
+
+        /// <summary>
+        /// Indicates whether the referenced component is read-only.
+        /// If the referenced object-type does not allow a readOnly field, then this field has no effect.
+        /// </summary>
+        public bool? ReadOnly { get; set; }
+
+        /// <summary>
+        /// Indicates whether the referenced component is write-only.
+        /// If the referenced object-type does not allow a writeOnly field, then this field has no effect.
+        /// </summary>
+        public bool? WriteOnly { get; set; }
+
+        /// <summary>
+        /// Example values which by default SHOULD override those of the referenced component.
+        /// If the referenced object-type does not allow examples, then this field has no effect.
+        /// </summary>
+        public IList<JsonNode>? Examples { get; set; }
+
         /// <summary>
         /// External resource in the reference.
         /// It maybe:
@@ -153,6 +190,12 @@ public OpenApiReference(OpenApiReference reference)
             Utils.CheckArgumentNull(reference);
             Summary = reference.Summary;
             Description = reference.Description;
+            Default = reference.Default;
+            Title = reference.Title;
+            Deprecated = reference.Deprecated;
+            ReadOnly = reference.ReadOnly;
+            WriteOnly = reference.WriteOnly;
+            Examples = reference.Examples;
             ExternalResource = reference.ExternalResource;
             Type = reference.Type;
             Id = reference.Id;
@@ -169,6 +212,17 @@ public void SerializeAsV31(IOpenApiWriter writer)
                 // summary and description are in 3.1 but not in 3.0
                 w.WriteProperty(OpenApiConstants.Summary, Summary);
                 w.WriteProperty(OpenApiConstants.Description, Description);
+
+                // Additional schema metadata annotations in 3.1
+                w.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
+                w.WriteProperty(OpenApiConstants.Title, Title);
+                w.WriteProperty(OpenApiConstants.Deprecated, Deprecated, false);
+                w.WriteProperty(OpenApiConstants.ReadOnly, ReadOnly, false);
+                w.WriteProperty(OpenApiConstants.WriteOnly, WriteOnly, false);
+                if (Examples != null && Examples.Any())
+                {
+                    w.WriteOptionalCollection(OpenApiConstants.Examples, Examples, (w, e) => w.WriteAny(e));
+                }
             });
         }
 
@@ -293,13 +347,15 @@ internal void EnsureHostDocumentIsSet(OpenApiDocument currentDocument)
         }
         private static string? GetPropertyValueFromNode(JsonObject jsonObject, string key) =>
         jsonObject.TryGetPropertyValue(key, out var valueNode) && valueNode is JsonValue valueCast && valueCast.TryGetValue<string>(out var strValue) ? strValue : null;
-        internal void SetSummaryAndDescriptionFromMapNode(MapNode mapNode)
+        internal void SetMetadataFromMapNode(MapNode mapNode)
         {
-            var (description, summary) = mapNode.JsonNode switch {
-                JsonObject jsonObject => (GetPropertyValueFromNode(jsonObject, OpenApiConstants.Description),
-                                            GetPropertyValueFromNode(jsonObject, OpenApiConstants.Summary)),
-                _ => (null, null)
-            };
+            if (mapNode.JsonNode is not JsonObject jsonObject) return;
+
+            // Summary and Description
+            var description = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Description);
+            var summary = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Summary);
+            var title = GetPropertyValueFromNode(jsonObject, OpenApiConstants.Title);
+
             if (!string.IsNullOrEmpty(description))
             {
                 Description = description;
@@ -308,6 +364,54 @@ internal void SetSummaryAndDescriptionFromMapNode(MapNode mapNode)
             {
                 Summary = summary;
             }
+            if (!string.IsNullOrEmpty(title))
+            {
+                Title = title;
+            }
+
+            // Boolean properties
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.Deprecated, out var deprecatedNode) && deprecatedNode is JsonValue deprecatedValue)
+            {
+                if (deprecatedValue.TryGetValue<bool>(out var deprecated))
+                {
+                    Deprecated = deprecated;
+                }
+            }
+
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.ReadOnly, out var readOnlyNode) && readOnlyNode is JsonValue readOnlyValue)
+            {
+                if (readOnlyValue.TryGetValue<bool>(out var readOnly))
+                {
+                    ReadOnly = readOnly;
+                }
+            }
+
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.WriteOnly, out var writeOnlyNode) && writeOnlyNode is JsonValue writeOnlyValue)
+            {
+                if (writeOnlyValue.TryGetValue<bool>(out var writeOnly))
+                {
+                    WriteOnly = writeOnly;
+                }
+            }
+
+            // Default value
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.Default, out var defaultNode))
+            {
+                Default = defaultNode;
+            }
+
+            // Examples
+            if (jsonObject.TryGetPropertyValue(OpenApiConstants.Examples, out var examplesNode) && examplesNode is JsonArray examplesArray)
+            {
+                Examples = new List<JsonNode>();
+                foreach (var example in examplesArray)
+                {
+                    if (example != null)
+                    {
+                        Examples.Add(example);
+                    }
+                }
+            }
         }
 
         internal void SetJsonPointerPath(string pointer, string nodeLocation)
@@ -329,10 +433,10 @@ internal void SetJsonPointerPath(string pointer, string nodeLocation)
         private static string ResolveRelativePointer(string nodeLocation, string relativeRef)
         {
             // Convert nodeLocation to path segments
-            var segments = nodeLocation.TrimStart('#').Split(['/'], StringSplitOptions.RemoveEmptyEntries).ToList();
+            var segments = nodeLocation.TrimStart('#').Split(new char[] {'/'}, StringSplitOptions.RemoveEmptyEntries).ToList();
 
             // Convert relativeRef to dynamic segments
-            var relativeSegments = relativeRef.TrimStart('#').Split(['/'], StringSplitOptions.RemoveEmptyEntries);
+            var relativeSegments = relativeRef.TrimStart('#').Split(new char[] {'/'}, StringSplitOptions.RemoveEmptyEntries);
 
             // Locate the first occurrence of relativeRef segments in the full path
             for (int i = 0; i <= segments.Count - relativeSegments.Length; i++)

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

@@ -40,8 +40,21 @@ public string? Description
             set => Reference.Description = value;
         }
 
+        /// <summary>
+        /// A short summary which by default SHOULD override that of the referenced component.
+        /// </summary>
+        public string? Summary
+        {
+            get => string.IsNullOrEmpty(Reference.Summary) ? null : Reference.Summary;
+            set => Reference.Summary = value;
+        }
+
         /// <inheritdoc/>
-        public string? Title { get => Target?.Title; }
+        public string? Title
+        {
+            get => string.IsNullOrEmpty(Reference.Title) ? Target?.Title : Reference.Title;
+            set => Reference.Title = value;
+        }
         /// <inheritdoc/>
         public Uri? Schema { get => Target?.Schema; }
         /// <inheritdoc/>
@@ -79,11 +92,23 @@ public string? Description
         /// <inheritdoc/>
         public decimal? MultipleOf { get => Target?.MultipleOf; }
         /// <inheritdoc/>
-        public JsonNode? Default { get => Target?.Default; }
+        public JsonNode? Default
+        {
+            get => Reference.Default ?? Target?.Default;
+            set => Reference.Default = value;
+        }
         /// <inheritdoc/>
-        public bool ReadOnly { get => Target?.ReadOnly ?? false; }
+        public bool ReadOnly
+        {
+            get => Reference.ReadOnly ?? Target?.ReadOnly ?? false;
+            set => Reference.ReadOnly = value;
+        }
         /// <inheritdoc/>
-        public bool WriteOnly { get => Target?.WriteOnly ?? false; }
+        public bool WriteOnly
+        {
+            get => Reference.WriteOnly ?? Target?.WriteOnly ?? false;
+            set => Reference.WriteOnly = value;
+        }
         /// <inheritdoc/>
         public IList<IOpenApiSchema>? AllOf { get => Target?.AllOf; }
         /// <inheritdoc/>
@@ -119,15 +144,23 @@ public string? Description
         /// <inheritdoc/>
         public JsonNode? Example { get => Target?.Example; }
         /// <inheritdoc/>
-        public IList<JsonNode>? Examples { get => Target?.Examples; }
+        public IList<JsonNode>? Examples
+        {
+            get => Reference.Examples ?? Target?.Examples;
+            set => Reference.Examples = value;
+        }
         /// <inheritdoc/>
         public IList<JsonNode>? Enum { get => Target?.Enum; }
         /// <inheritdoc/>
         public bool UnevaluatedProperties { get => Target?.UnevaluatedProperties ?? false; }
         /// <inheritdoc/>
         public OpenApiExternalDocs? ExternalDocs { get => Target?.ExternalDocs; }
         /// <inheritdoc/>
-        public bool Deprecated { get => Target?.Deprecated ?? false; }
+        public bool Deprecated
+        {
+            get => Reference.Deprecated ?? Target?.Deprecated ?? false;
+            set => Reference.Deprecated = value;
+        }
         /// <inheritdoc/>
         public OpenApiXml? Xml { get => Target?.Xml; }
         /// <inheritdoc/>

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

@@ -368,7 +368,7 @@ public static IOpenApiSchema LoadSchema(ParseNode node, OpenApiDocument hostDocu
             {
                 var reference = GetReferenceIdAndExternalResource(pointer);
                 var result = new OpenApiSchemaReference(reference.Item1, hostDocument, reference.Item2);
-                result.Reference.SetSummaryAndDescriptionFromMapNode(mapNode);
+                result.Reference.SetMetadataFromMapNode(mapNode);
                 result.Reference.SetJsonPointerPath(pointer, nodeLocation);
                 return result;
             }            

src/Microsoft.OpenApi/Services/OpenApiWorkspace.cs

@@ -347,7 +347,7 @@ public bool Contains(string location)
 
             if (uri is not null)
             {
-                pathSegments = uri.Fragment.Split(['/'], StringSplitOptions.RemoveEmptyEntries);
+                pathSegments = uri.Fragment.Split(new char[] {'/'}, StringSplitOptions.RemoveEmptyEntries);
 
                 // Build the base path for the root schema: "#/components/schemas/person"
                 var fragment = OpenApiConstants.ComponentsSegment + ReferenceType.Schema.GetDisplayName() + ComponentSegmentSeparator + pathSegments[3];