fix: renames annotations schema property to metadata to match #2241

src/Microsoft.OpenApi/Interfaces/IMetadataContainer.cs

@@ -3,17 +3,16 @@
 
 using System.Collections.Generic;
 
-namespace Microsoft.OpenApi.Interfaces
+namespace Microsoft.OpenApi.Interfaces;
+/// <summary>
+/// Represents an Open API element that can be annotated with
+/// non-serializable properties in a property bag. 
+/// </summary>
+public interface IMetadataContainer
 {
     /// <summary>
-    /// Represents an Open API element that can be annotated with
-    /// non-serializable properties in a property bag. 
+    /// A collection of properties associated with the current OpenAPI element to be used by the application.
+    /// Metadata are NOT (de)serialized with the schema and can be used for custom properties.
     /// </summary>
-    public interface IMetadataContainer
-    {
-        /// <summary>
-        /// A collection of properties associated with the current OpenAPI element.
-        /// </summary>
-        Dictionary<string, object>? Metadata { get; set; }
-    }
+    Dictionary<string, object>? Metadata { get; set; }
 }

src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchema.cs

@@ -17,6 +17,7 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// </summary>
     public string? Title { get; }
 
+
     /// <summary>
     /// $schema, a JSON Schema dialect identifier. Value must be a URI
     /// </summary>
@@ -280,12 +281,6 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// </summary>
     public Dictionary<string, JsonNode>? UnrecognizedKeywords { get; }
 
-    /// <summary>
-    /// Any annotation to attach to the schema to be used by the application.
-    /// Annotations are NOT (de)serialized with the schema and can be used for custom properties.
-    /// </summary>
-    public Dictionary<string, object>? Annotations { get; }
-
     /// <summary>
     /// Follow JSON Schema definition:https://json-schema.org/draft/2020-12/json-schema-validation#section-6.5.4
     /// </summary>

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -18,7 +18,7 @@
     /// <summary>
     /// The Schema Object allows the definition of input and output data types.
     /// </summary>
-    public class OpenApiSchema : IOpenApiExtensible, IOpenApiSchema
+    public class OpenApiSchema : IOpenApiExtensible, IOpenApiSchema, IMetadataContainer
     {
         /// <inheritdoc />
         public string? Title { get; set; }
@@ -248,7 +248,7 @@
         public Dictionary<string, JsonNode>? UnrecognizedKeywords { get; set; }
 
         /// <inheritdoc />
-        public Dictionary<string, object>? Annotations { get; set; }
+        public Dictionary<string, object>? Metadata { get; set; }
 
         /// <inheritdoc />
         public Dictionary<string, HashSet<string>>? DependentRequired { get; set; }
@@ -262,7 +262,7 @@
         /// Initializes a copy of <see cref="IOpenApiSchema"/> object
         /// </summary>
         /// <param name="schema">The schema object to copy from.</param>
         internal OpenApiSchema(IOpenApiSchema schema)
         {
             Utils.CheckArgumentNull(schema);
             Title = schema.Title ?? Title;
@@ -317,7 +317,7 @@
             Deprecated = schema.Deprecated;
             Xml = schema.Xml != null ? new(schema.Xml) : null;
             Extensions = schema.Extensions != null ? new Dictionary<string, IOpenApiExtension>(schema.Extensions) : null;
-            Annotations = schema.Annotations != null ? new Dictionary<string, object>(schema.Annotations) : null;
+            Metadata = schema is IMetadataContainer { Metadata: not null } mContainer ? new Dictionary<string, object>(mContainer.Metadata) : null;
             UnrecognizedKeywords = schema.UnrecognizedKeywords != null ? new Dictionary<string, JsonNode>(schema.UnrecognizedKeywords) : null;
             DependentRequired = schema.DependentRequired != null ? new Dictionary<string, HashSet<string>>(schema.DependentRequired) : null;
         }
@@ -334,23 +334,23 @@
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
         private static void SerializeBounds(IOpenApiWriter writer, OpenApiSpecVersion version, string propertyName, string exclusivePropertyName, string isExclusivePropertyName, string? value, string? exclusiveValue, bool? isExclusiveValue)
         {
             if (version >= OpenApiSpecVersion.OpenApi3_1)
             {
                 if (!string.IsNullOrEmpty(exclusiveValue) && exclusiveValue is not null)
                 {
                     // was explicitly set in the document or object model
                     writer.WritePropertyName(exclusivePropertyName);
                     writer.WriteRaw(exclusiveValue);
                 }
                 else if (isExclusiveValue == true && !string.IsNullOrEmpty(value) && value is not null)
                 {
                     // came from parsing an old document
                     writer.WritePropertyName(exclusivePropertyName);
                     writer.WriteRaw(value);
                 }
                 else if (!string.IsNullOrEmpty(value) && value is not null)
                 {
                     // was explicitly set in the document or object model
                     writer.WritePropertyName(propertyName);
@@ -359,14 +359,14 @@
             }
             else
             {
                 if (!string.IsNullOrEmpty(exclusiveValue) && exclusiveValue is not null)
                 {
                     // was explicitly set in a new document being downcast or object model
                     writer.WritePropertyName(propertyName);
                     writer.WriteRaw(exclusiveValue);
                     writer.WriteProperty(isExclusivePropertyName, true);
                 }
                 else if (!string.IsNullOrEmpty(value) && value is not null)
                 {
                     // came from parsing an old document, we're just mirroring the information
                     writer.WritePropertyName(propertyName);
@@ -428,7 +428,7 @@
             // required
             writer.WriteOptionalCollection(OpenApiConstants.Required, Required, (w, s) =>
             {
                 if (!string.IsNullOrEmpty(s) && s is not null)
                 {
                     w.WriteValue(s);
                 }
@@ -749,7 +749,7 @@
             writer.WriteEndObject();
         }
 
         private void SerializeTypeProperty(JsonSchemaType? type, IOpenApiWriter writer, OpenApiSpecVersion version)
         {
             // check whether nullable is true for upcasting purposes
             var isNullable = (Type.HasValue && Type.Value.HasFlag(JsonSchemaType.Null)) ||

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

@@ -139,9 +139,6 @@ public string? Description
         /// <inheritdoc/>
         public Dictionary<string, JsonNode>? UnrecognizedKeywords { get => Target?.UnrecognizedKeywords; }
 
-        /// <inheritdoc/>
-        public Dictionary<string, object>? Annotations { get => Target?.Annotations; }
-
         /// <inheritdoc/>
         public Dictionary<string, HashSet<string>>? DependentRequired { get => Target?.DependentRequired; }
 

test/Microsoft.OpenApi.Readers.Tests/OpenApiWorkspaceTests/OpenApiWorkspaceStreamTests.cs

@@ -104,7 +104,9 @@ public async Task LoadDocumentWithExternalReferencesInSubDirectories()
             Assert.Equal(JsonSchemaType.Array, petsSchema.Type);
 
             var petSchema = petsSchema.Items;
-            Assert.IsType<OpenApiSchemaReference>(petSchema);
+            var petSchemaReference = Assert.IsType<OpenApiSchemaReference>(petSchema);
+            var petSchemaTarget = petSchemaReference.RecursiveTarget;
+            Assert.NotNull(petSchemaTarget);
 
             Assert.Equivalent(new OpenApiSchema
             {
@@ -125,7 +127,7 @@ public async Task LoadDocumentWithExternalReferencesInSubDirectories()
                         Type = JsonSchemaType.String
                     }
                 }
-            }, petSchema);
+            }, petSchemaTarget);
         }
     }
 

test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs

@@ -36,7 +36,7 @@ public class OpenApiDocumentTests
                         ["property1"] = new OpenApiSchema()
                         {
                             Type = JsonSchemaType.String,
-                            Annotations = new Dictionary<string, object> { { "key1", "value" } }
+                            Metadata = new Dictionary<string, object> { { "key1", "value" } }
                         }
                     }
                 },
@@ -55,10 +55,10 @@ public class OpenApiDocumentTests
                         ["property1"] = new OpenApiSchema()
                         {
                             Type = JsonSchemaType.String,
-                            Annotations = new Dictionary<string, object> { { "key1", "value" } }
+                            Metadata = new Dictionary<string, object> { { "key1", "value" } }
                         }
                     },
-                    Annotations = new Dictionary<string, object> { { "key1", "value" } },
+                    Metadata = new Dictionary<string, object> { { "key1", "value" } },
                 },
                 ["schema2"] = new OpenApiSchema()
                 {

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.cs

@@ -38,7 +38,7 @@ public class OpenApiSchemaTests
             {
                 Url = new("http://example.com/externalDocs")
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } }
+            Metadata = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } }
         };
 
         public static readonly OpenApiSchema AdvancedSchemaObject = new()
@@ -473,24 +473,24 @@ public void OpenApiSchemaCopyConstructorSucceeds()
         }
 
         [Fact]
-        public void OpenApiSchemaCopyConstructorWithAnnotationsSucceeds()
+        public void OpenApiSchemaCopyConstructorWithMetadataSucceeds()
         {
             var baseSchema = new OpenApiSchema
             {
-                Annotations = new Dictionary<string, object>
+                Metadata = new Dictionary<string, object>
                 {
                     ["key1"] = "value1",
                     ["key2"] = 2
                 }
             };
 
-            var actualSchema = baseSchema.CreateShallowCopy();
+            var actualSchema = Assert.IsType<OpenApiSchema>(baseSchema.CreateShallowCopy());
 
-            Assert.Equal(baseSchema.Annotations["key1"], actualSchema.Annotations["key1"]);
+            Assert.Equal(baseSchema.Metadata["key1"], actualSchema.Metadata["key1"]);
 
-            baseSchema.Annotations["key1"] = "value2";
+            baseSchema.Metadata["key1"] = "value2";
 
-            Assert.NotEqual(baseSchema.Annotations["key1"], actualSchema.Annotations["key1"]);
+            Assert.NotEqual(baseSchema.Metadata["key1"], actualSchema.Metadata["key1"]);
         }
 
         public static TheoryData<JsonNode> SchemaExamples()

test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt

@@ -415,7 +415,6 @@ namespace Microsoft.OpenApi.Models.Interfaces
         Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema? AdditionalProperties { get; }
         bool AdditionalPropertiesAllowed { get; }
         System.Collections.Generic.List<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>? AllOf { get; }
-        System.Collections.Generic.Dictionary<string, object>? Annotations { get; }
         System.Collections.Generic.List<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>? AnyOf { get; }
         string? Comment { get; }
         string? Const { get; }
@@ -1010,13 +1009,12 @@ namespace Microsoft.OpenApi.Models
         public OpenApiResponses() { }
         public OpenApiResponses(Microsoft.OpenApi.Models.OpenApiResponses openApiResponses) { }
     }
-    public class OpenApiSchema : Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReferenceable, Microsoft.OpenApi.Interfaces.IOpenApiSerializable, Microsoft.OpenApi.Interfaces.IShallowCopyable<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>, Microsoft.OpenApi.Models.Interfaces.IOpenApiDescribedElement, Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema
+    public class OpenApiSchema : Microsoft.OpenApi.Interfaces.IMetadataContainer, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReadOnlyExtensible, Microsoft.OpenApi.Interfaces.IOpenApiReferenceable, Microsoft.OpenApi.Interfaces.IOpenApiSerializable, Microsoft.OpenApi.Interfaces.IShallowCopyable<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>, Microsoft.OpenApi.Models.Interfaces.IOpenApiDescribedElement, Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema
     {
         public OpenApiSchema() { }
         public Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema? AdditionalProperties { get; set; }
         public bool AdditionalPropertiesAllowed { get; set; }
         public System.Collections.Generic.List<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>? AllOf { get; set; }
-        public System.Collections.Generic.Dictionary<string, object>? Annotations { get; set; }
         public System.Collections.Generic.List<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>? AnyOf { get; set; }
         public string? Comment { get; set; }
         public string? Const { get; set; }
@@ -1042,6 +1040,7 @@ namespace Microsoft.OpenApi.Models
         public int? MaxLength { get; set; }
         public int? MaxProperties { get; set; }
         public string? Maximum { get; set; }
+        public System.Collections.Generic.Dictionary<string, object>? Metadata { get; set; }
         public int? MinItems { get; set; }
         public int? MinLength { get; set; }
         public int? MinProperties { get; set; }
@@ -1348,7 +1347,6 @@ namespace Microsoft.OpenApi.Models.References
         public Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema? AdditionalProperties { get; }
         public bool AdditionalPropertiesAllowed { get; }
         public System.Collections.Generic.List<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>? AllOf { get; }
-        public System.Collections.Generic.Dictionary<string, object>? Annotations { get; }
         public System.Collections.Generic.List<Microsoft.OpenApi.Models.Interfaces.IOpenApiSchema>? AnyOf { get; }
         public string? Comment { get; }
         public string? Const { get; }