Add metadata annotations to OpenApiSchemaReference

- Add Default, Title, Deprecated, ReadOnly, WriteOnly, Examples to OpenApiReference
- Update OpenApiSchemaReference properties to use override pattern like Description
- Add Summary property to OpenApiSchemaReference
- Update serialization for v3.1 to include new annotation fields
- Update deserialization to handle new annotation fields
- Add comprehensive unit tests for new functionality
- Update public API approvals

Co-authored-by: baywet <[email protected]>

Author: Copilot

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)

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;
             }