refactor: rename annotations to metadata

MaggieKimani1 · MaggieKimani1 · commit c71b5de31da6 · 2025-03-10T17:05:42.000+03:00
diff --git a/src/Microsoft.OpenApi/Interfaces/IMetadataContainer.cs b/src/Microsoft.OpenApi/Interfaces/IMetadataContainer.cs
@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+﻿// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
 using System.Collections.Generic;
@@ -9,11 +9,11 @@ namespace Microsoft.OpenApi.Interfaces
     /// Represents an Open API element that can be annotated with
     /// non-serializable properties in a property bag. 
     /// </summary>
-    public interface IOpenApiAnnotatable
+    public interface IMetadataContainer
     {
         /// <summary>
         /// A collection of properties associated with the current OpenAPI element.
         /// </summary>
-        IDictionary<string, object> Annotations { get; set; }
+        IDictionary<string, object> Metadata { get; set; }
     }
 }
diff --git a/src/Microsoft.OpenApi/Models/OpenApiDocument.cs b/src/Microsoft.OpenApi/Models/OpenApiDocument.cs
@@ -24,7 +24,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Describes an OpenAPI object (OpenAPI document). See: https://spec.openapis.org
     /// </summary>
-    public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
+    public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IMetadataContainer
     {
         /// <summary>
         /// Register components in the document to the workspace
@@ -109,7 +109,7 @@ public ISet<OpenApiTag>? Tags
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <inheritdoc />
-        public IDictionary<string, object>? Annotations { get; set; }
+        public IDictionary<string, object>? Metadata { get; set; }
 
         /// <summary>
         /// Implements IBaseDocument
@@ -143,7 +143,7 @@ public OpenApiDocument(OpenApiDocument? document)
             Tags = document?.Tags != null ? new HashSet<OpenApiTag>(document.Tags, OpenApiTagComparer.Instance) : null;
             ExternalDocs = document?.ExternalDocs != null ? new(document?.ExternalDocs) : null;
             Extensions = document?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(document.Extensions) : null;
-            Annotations = document?.Annotations != null ? new Dictionary<string, object>(document.Annotations) : null;
+            Metadata = document?.Metadata != null ? new Dictionary<string, object>(document.Metadata) : null;
             BaseUri = document?.BaseUri != null ? document.BaseUri : new(OpenApiConstants.BaseRegistryUri + Guid.NewGuid());
         }
 
diff --git a/src/Microsoft.OpenApi/Models/OpenApiOperation.cs b/src/Microsoft.OpenApi/Models/OpenApiOperation.cs
@@ -16,7 +16,7 @@ namespace Microsoft.OpenApi.Models
     /// <summary>
     /// Operation Object.
     /// </summary>
-    public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible, IOpenApiAnnotatable
+    public class OpenApiOperation : IOpenApiSerializable, IOpenApiExtensible, IMetadataContainer
     {
         /// <summary>
         /// Default value for <see cref="Deprecated"/>.
@@ -127,7 +127,7 @@ public ISet<OpenApiTagReference>? Tags
         public IDictionary<string, IOpenApiExtension>? Extensions { get; set; } = new Dictionary<string, IOpenApiExtension>();
 
         /// <inheritdoc />
-        public IDictionary<string, object>? Annotations { get; set; }
+        public IDictionary<string, object>? Metadata { get; set; }
 
         /// <summary>
         /// Parameterless constructor
@@ -153,7 +153,7 @@ public OpenApiOperation(OpenApiOperation operation)
             Security = operation.Security != null ? new List<OpenApiSecurityRequirement>(operation.Security) : null;
             Servers = operation.Servers != null ? new List<OpenApiServer>(operation.Servers) : null;
             Extensions = operation.Extensions != null ? new Dictionary<string, IOpenApiExtension>(operation.Extensions) : null;
-            Annotations = operation.Annotations != null ? new Dictionary<string, object>(operation.Annotations) : null;
+            Metadata = operation.Metadata != null ? new Dictionary<string, object>(operation.Metadata) : null;
         }
 
         /// <summary>
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiDocumentTests.cs
@@ -92,7 +92,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelReferencingComponents
         };
 
@@ -102,7 +102,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelSelfReferencingComponentsWithOtherProperties
         };
 
@@ -112,7 +112,7 @@ public class OpenApiDocumentTests
             {
                 Version = "1.0.0"
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = TopLevelSelfReferencingComponents
         };
 
@@ -489,7 +489,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponentsWithReference
         };
 
@@ -865,7 +865,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1024,7 +1024,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1324,7 +1324,7 @@ public class OpenApiDocumentTests
                     }
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value" } },
+            Metadata = new Dictionary<string, object> { { "key1", "value" } },
             Components = AdvancedComponents
         };
 
@@ -1830,7 +1830,7 @@ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()
         {
             var baseDocument = new OpenApiDocument
             {
-                Annotations = new Dictionary<string, object>
+                Metadata = new Dictionary<string, object>
                 {
                     ["key1"] = "value1",
                     ["key2"] = 2
@@ -1839,11 +1839,11 @@ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()
 
             var actualDocument = new OpenApiDocument(baseDocument);
 
-            Assert.Equal(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);
+            Assert.Equal(baseDocument.Metadata["key1"], actualDocument.Metadata["key1"]);
 
-            baseDocument.Annotations["key1"] = "value2";
+            baseDocument.Metadata["key1"] = "value2";
 
-            Assert.NotEqual(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);
+            Assert.NotEqual(baseDocument.Metadata["key1"], actualDocument.Metadata["key1"]);
         }
 
         [Fact]
diff --git a/test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs b/test/Microsoft.OpenApi.Tests/Models/OpenApiOperationTests.cs
@@ -84,7 +84,7 @@ public class OpenApiOperationTests
                     Description = "serverDescription"
                 }
             },
-            Annotations = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },
+            Metadata = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },
         };
 
         private static OpenApiOperation _advancedOperationWithTagsAndSecurity => new()
@@ -844,7 +844,7 @@ public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()
         {
             var baseOperation = new OpenApiOperation
             {
-                Annotations = new Dictionary<string, object>
+                Metadata = new Dictionary<string, object>
                 {
                     ["key1"] = "value1",
                     ["key2"] = 2
@@ -853,11 +853,11 @@ public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()
 
             var actualOperation = new OpenApiOperation(baseOperation);
 
-            Assert.Equal(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);
+            Assert.Equal(baseOperation.Metadata["key1"], actualOperation.Metadata["key1"]);
 
-            baseOperation.Annotations["key1"] = "value2";
+            baseOperation.Metadata["key1"] = "value2";
 
-            Assert.NotEqual(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);
+            Assert.NotEqual(baseOperation.Metadata["key1"], actualOperation.Metadata["key1"]);
         }
     }
 }
diff --git a/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt b/test/Microsoft.OpenApi.Tests/PublicApi/PublicApi.approved.txt
@@ -199,9 +199,9 @@ namespace Microsoft.OpenApi.Extensions
 namespace Microsoft.OpenApi.Interfaces
 {
     public interface IDiagnostic { }
-    public interface IOpenApiAnnotatable
+    public interface IMetadataContainer
     {
-        System.Collections.Generic.IDictionary<string, object> Annotations { get; set; }
+        System.Collections.Generic.IDictionary<string, object> Metadata { get; set; }
     }
     public interface IOpenApiElement { }
     public interface IOpenApiExtensible : Microsoft.OpenApi.Interfaces.IOpenApiElement
@@ -706,17 +706,17 @@ namespace Microsoft.OpenApi.Models
         public void SerializeAsV3(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
         public void SerializeAsV31(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
     }
-    public class OpenApiDocument : Microsoft.OpenApi.Interfaces.IOpenApiAnnotatable, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
+    public class OpenApiDocument : Microsoft.OpenApi.Interfaces.IMetadataContainer, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
     {
         public OpenApiDocument() { }
         public OpenApiDocument(Microsoft.OpenApi.Models.OpenApiDocument? document) { }
-        public System.Collections.Generic.IDictionary<string, object>? Annotations { get; set; }
         public System.Uri BaseUri { get; }
         public Microsoft.OpenApi.Models.OpenApiComponents? Components { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.Interfaces.IOpenApiExtension>? Extensions { get; set; }
         public Microsoft.OpenApi.Models.OpenApiExternalDocs? ExternalDocs { get; set; }
         public Microsoft.OpenApi.Models.OpenApiInfo Info { get; set; }
         public System.Uri? JsonSchemaDialect { get; set; }
+        public System.Collections.Generic.IDictionary<string, object>? Metadata { get; set; }
         public Microsoft.OpenApi.Models.OpenApiPaths Paths { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.OpenApiSecurityRequirement>? Security { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.OpenApiServer>? Servers { get; set; }
@@ -894,17 +894,17 @@ namespace Microsoft.OpenApi.Models
         public void SerializeAsV3(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
         public void SerializeAsV31(Microsoft.OpenApi.Writers.IOpenApiWriter writer) { }
     }
-    public class OpenApiOperation : Microsoft.OpenApi.Interfaces.IOpenApiAnnotatable, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
+    public class OpenApiOperation : Microsoft.OpenApi.Interfaces.IMetadataContainer, Microsoft.OpenApi.Interfaces.IOpenApiElement, Microsoft.OpenApi.Interfaces.IOpenApiExtensible, Microsoft.OpenApi.Interfaces.IOpenApiSerializable
     {
         public const bool DeprecatedDefault = false;
         public OpenApiOperation() { }
         public OpenApiOperation(Microsoft.OpenApi.Models.OpenApiOperation operation) { }
-        public System.Collections.Generic.IDictionary<string, object>? Annotations { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.Models.Interfaces.IOpenApiCallback>? Callbacks { get; set; }
         public bool Deprecated { get; set; }
         public string? Description { get; set; }
         public System.Collections.Generic.IDictionary<string, Microsoft.OpenApi.Interfaces.IOpenApiExtension>? Extensions { get; set; }
         public Microsoft.OpenApi.Models.OpenApiExternalDocs? ExternalDocs { get; set; }
+        public System.Collections.Generic.IDictionary<string, object>? Metadata { get; set; }
         public string? OperationId { get; set; }
         public System.Collections.Generic.IList<Microsoft.OpenApi.Models.Interfaces.IOpenApiParameter>? Parameters { get; set; }
         public Microsoft.OpenApi.Models.Interfaces.IOpenApiRequestBody? RequestBody { get; set; }

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// Copyright (c) Microsoft Corporation. All rights reserved.`
	`1`	`+// Copyright (c) Microsoft Corporation. All rights reserved.`
`2`	`2`	`// Licensed under the MIT license.`
`3`	`3`
`4`	`4`	`using System.Collections.Generic;`
`@@ -9,11 +9,11 @@ namespace Microsoft.OpenApi.Interfaces`
`9`	`9`	`/// Represents an Open API element that can be annotated with`
`10`	`10`	`/// non-serializable properties in a property bag.`
`11`	`11`	`/// </summary>`
`12`		`- public interface IOpenApiAnnotatable`
	`12`	`+ public interface IMetadataContainer`
`13`	`13`	`{`
`14`	`14`	`/// <summary>`
`15`	`15`	`/// A collection of properties associated with the current OpenAPI element.`
`16`	`16`	`/// </summary>`
`17`		`- IDictionary<string, object> Annotations { get; set; }`
	`17`	`+ IDictionary<string, object> Metadata { get; set; }`
`18`	`18`	`}`
`19`	`19`	`}`
Original file line number	Diff line number	Diff line change
`@@ -92,7 +92,7 @@ public class OpenApiDocumentTests`
`92`	`92`	`{`
`93`	`93`	`Version = "1.0.0"`
`94`	`94`	`},`
`95`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`95`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`96`	`96`	`Components = TopLevelReferencingComponents`
`97`	`97`	`};`
`98`	`98`
`@@ -102,7 +102,7 @@ public class OpenApiDocumentTests`
`102`	`102`	`{`
`103`	`103`	`Version = "1.0.0"`
`104`	`104`	`},`
`105`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`105`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`106`	`106`	`Components = TopLevelSelfReferencingComponentsWithOtherProperties`
`107`	`107`	`};`
`108`	`108`
`@@ -112,7 +112,7 @@ public class OpenApiDocumentTests`
`112`	`112`	`{`
`113`	`113`	`Version = "1.0.0"`
`114`	`114`	`},`
`115`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`115`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`116`	`116`	`Components = TopLevelSelfReferencingComponents`
`117`	`117`	`};`
`118`	`118`
`@@ -489,7 +489,7 @@ public class OpenApiDocumentTests`
`489`	`489`	`}`
`490`	`490`	`}`
`491`	`491`	`},`
`492`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`492`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`493`	`493`	`Components = AdvancedComponentsWithReference`
`494`	`494`	`};`
`495`	`495`
`@@ -865,7 +865,7 @@ public class OpenApiDocumentTests`
`865`	`865`	`}`
`866`	`866`	`}`
`867`	`867`	`},`
`868`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`868`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`869`	`869`	`Components = AdvancedComponents`
`870`	`870`	`};`
`871`	`871`
`@@ -1024,7 +1024,7 @@ public class OpenApiDocumentTests`
`1024`	`1024`	`}`
`1025`	`1025`	`}`
`1026`	`1026`	`},`
`1027`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`1027`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`1028`	`1028`	`Components = AdvancedComponents`
`1029`	`1029`	`};`
`1030`	`1030`
`@@ -1324,7 +1324,7 @@ public class OpenApiDocumentTests`
`1324`	`1324`	`}`
`1325`	`1325`	`}`
`1326`	`1326`	`},`
`1327`		`- Annotations = new Dictionary<string, object> { { "key1", "value" } },`
	`1327`	`+ Metadata = new Dictionary<string, object> { { "key1", "value" } },`
`1328`	`1328`	`Components = AdvancedComponents`
`1329`	`1329`	`};`
`1330`	`1330`
`@@ -1830,7 +1830,7 @@ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()`
`1830`	`1830`	`{`
`1831`	`1831`	`var baseDocument = new OpenApiDocument`
`1832`	`1832`	`{`
`1833`		`- Annotations = new Dictionary<string, object>`
	`1833`	`+ Metadata = new Dictionary<string, object>`
`1834`	`1834`	`{`
`1835`	`1835`	`["key1"] = "value1",`
`1836`	`1836`	`["key2"] = 2`
`@@ -1839,11 +1839,11 @@ public void OpenApiDocumentCopyConstructorWithAnnotationsSucceeds()`
`1839`	`1839`
`1840`	`1840`	`var actualDocument = new OpenApiDocument(baseDocument);`
`1841`	`1841`
`1842`		`- Assert.Equal(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);`
	`1842`	`+ Assert.Equal(baseDocument.Metadata["key1"], actualDocument.Metadata["key1"]);`
`1843`	`1843`
`1844`		`- baseDocument.Annotations["key1"] = "value2";`
	`1844`	`+ baseDocument.Metadata["key1"] = "value2";`
`1845`	`1845`
`1846`		`- Assert.NotEqual(baseDocument.Annotations["key1"], actualDocument.Annotations["key1"]);`
	`1846`	`+ Assert.NotEqual(baseDocument.Metadata["key1"], actualDocument.Metadata["key1"]);`
`1847`	`1847`	`}`
`1848`	`1848`
`1849`	`1849`	`[Fact]`
Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ public class OpenApiOperationTests`
`84`	`84`	`Description = "serverDescription"`
`85`	`85`	`}`
`86`	`86`	`},`
`87`		`- Annotations = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },`
	`87`	`+ Metadata = new Dictionary<string, object> { { "key1", "value1" }, { "key2", 2 } },`
`88`	`88`	`};`
`89`	`89`
`90`	`90`	`private static OpenApiOperation _advancedOperationWithTagsAndSecurity => new()`
`@@ -844,7 +844,7 @@ public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()`
`844`	`844`	`{`
`845`	`845`	`var baseOperation = new OpenApiOperation`
`846`	`846`	`{`
`847`		`- Annotations = new Dictionary<string, object>`
	`847`	`+ Metadata = new Dictionary<string, object>`
`848`	`848`	`{`
`849`	`849`	`["key1"] = "value1",`
`850`	`850`	`["key2"] = 2`
`@@ -853,11 +853,11 @@ public void OpenApiOperationCopyConstructorWithAnnotationsSucceeds()`
`853`	`853`
`854`	`854`	`var actualOperation = new OpenApiOperation(baseOperation);`
`855`	`855`
`856`		`- Assert.Equal(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);`
	`856`	`+ Assert.Equal(baseOperation.Metadata["key1"], actualOperation.Metadata["key1"]);`
`857`	`857`
`858`		`- baseOperation.Annotations["key1"] = "value2";`
	`858`	`+ baseOperation.Metadata["key1"] = "value2";`
`859`	`859`
`860`		`- Assert.NotEqual(baseOperation.Annotations["key1"], actualOperation.Annotations["key1"]);`
	`860`	`+ Assert.NotEqual(baseOperation.Metadata["key1"], actualOperation.Metadata["key1"]);`
`861`	`861`	`}`
`862`	`862`	`}`
`863`	`863`	`}`