microsoft · baywet · Feb 3, 2025 · Jan 29, 2025 · Jan 29, 2025 · Jan 30, 2025
diff --git a/src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceHolder.cs b/src/Microsoft.OpenApi/Interfaces/IOpenApiReferenceHolder.cs
@@ -8,22 +8,14 @@ namespace Microsoft.OpenApi.Interfaces
    /// <summary>
    /// A generic interface for OpenApiReferenceable objects that have a target.
    /// </summary>
-    /// <typeparam name="T">Type of the target being referenced</typeparam>
-    public interface IOpenApiReferenceHolder<out T> : IOpenApiReferenceHolder where T : IOpenApiReferenceable
+    /// <typeparam name="T">The type of the target being referenced</typeparam>
+    /// <typeparam name="V">The type of the interface implemented by both the target and the reference type</typeparam>
+    public interface IOpenApiReferenceHolder<out T, V> : IOpenApiReferenceHolder where T : IOpenApiReferenceable, V
    {
        /// <summary>
        /// Gets the resolved target object.
        /// </summary>
        T Target { get; }
-    }
-    /// <summary>
-    /// A generic interface for OpenApiReferenceable objects that have a target.
-    /// </summary>
-    /// <typeparam name="T">The type of the target being referenced</typeparam>
-    /// <typeparam name="V">The type of the interface implemented by both the target and the reference type</typeparam>
-    public interface IOpenApiReferenceHolder<out T, V> : IOpenApiReferenceHolder<T> where T : IOpenApiReferenceable, V
-    {
-        //TODO merge this interface with the previous once all implementations are updated
        /// <summary>
        /// Copy the reference as a target element with overrides.
        /// </summary>
@@ -37,8 +29,7 @@ public interface IOpenApiReferenceHolder : IOpenApiSerializable
        /// <summary>
        /// Indicates if object is populated with data or is just a reference to the data
        /// </summary>
-        bool UnresolvedReference { get; set; }
-        //TODO the UnresolvedReference property setter should be removed and a default implementation that checks whether the target is null for the getter should be provided instead
+        bool UnresolvedReference { get; }

        /// <summary>
        /// Reference object.

diff --git a/src/Microsoft.OpenApi/Interfaces/IShallowCopyable.cs b/src/Microsoft.OpenApi/Interfaces/IShallowCopyable.cs
@@ -0,0 +1,12 @@
+namespace Microsoft.OpenApi.Interfaces;
+/// <summary>
+/// Interface for shallow copyable objects.
+/// </summary>
+/// <typeparam name="T">The type of the resulting object</typeparam>
+public interface IShallowCopyable<out T>
+{
+    /// <summary>
+    /// Create a shallow copy of the current instance.
+    /// </summary>
+    T CreateShallowCopy();
+}
diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiCallback.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiCallback.cs
@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the callback object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiCallback : IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiCallback : IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiCallback>
 {
    /// <summary>
    /// A Path Item Object used to define a callback request and expected responses.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiExample.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiExample.cs
@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the example object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiExample>
 {
    /// <summary>
    /// Embedded literal example. The value field and externalValue field are mutually

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiHeader.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiHeader.cs
@@ -9,7 +9,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the headers object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiHeader>
 {
    /// <summary>
    /// Determines whether this header is mandatory.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiLink.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiLink.cs
@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the link object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiLink : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiLink : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiLink>
 {
    /// <summary>
    /// A relative or absolute reference to an OAS operation.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiParameter.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiParameter.cs
@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the parameter object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiParameter>
 {
    /// <summary>
    /// REQUIRED. The name of the parameter. Parameter names are case sensitive.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiPathItem.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiPathItem.cs
@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the path item object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiPathItem : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiPathItem : IOpenApiDescribedElement, IOpenApiSummarizedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiPathItem>
 {
    /// <summary>
    /// Gets the definition of operations on this path.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiRequestBody.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiRequestBody.cs
@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the request body object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiRequestBody : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiRequestBody>
 {
    /// <summary>
    /// Determines if the request body is required in the request. Defaults to false.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiResponse.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiResponse.cs
@@ -7,7 +7,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the response object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiResponse : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiResponse>
 {
    /// <summary>
    /// Maps a header name to its definition.

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchema.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSchema.cs
@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the schema object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSchema>
 {

    /// <summary>

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSecurityScheme.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiSecurityScheme.cs
@@ -8,7 +8,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the security scheme object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible
+public interface IOpenApiSecurityScheme : IOpenApiDescribedElement, IOpenApiSerializable, IOpenApiReadOnlyExtensible, IShallowCopyable<IOpenApiSecurityScheme>
 {
    /// <summary>
    /// REQUIRED. The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".

diff --git a/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiTag.cs b/src/Microsoft.OpenApi/Models/Interfaces/IOpenApiTag.cs
@@ -6,7 +6,7 @@ namespace Microsoft.OpenApi.Models.Interfaces;
 /// Defines the base properties for the path item object.
 /// This interface is provided for type assertions but should not be implemented by package consumers beyond automatic mocking.
 /// </summary>
-public interface IOpenApiTag : IOpenApiSerializable, IOpenApiReadOnlyExtensible, IOpenApiReadOnlyDescribedElement
+public interface IOpenApiTag : IOpenApiSerializable, IOpenApiReadOnlyExtensible, IOpenApiReadOnlyDescribedElement, IShallowCopyable<IOpenApiTag>
 {
    /// <summary>
    /// The name of the tag.

diff --git a/src/Microsoft.OpenApi/Models/OpenApiCallback.cs b/src/Microsoft.OpenApi/Models/OpenApiCallback.cs
@@ -33,8 +33,9 @@ public OpenApiCallback() { }
        /// <summary>
        /// Initializes a copy of an <see cref="OpenApiCallback"/> object
        /// </summary>
-        public OpenApiCallback(IOpenApiCallback callback)
+        internal OpenApiCallback(IOpenApiCallback callback)
        {
+            Utils.CheckArgumentNull(callback);
            PathItems = callback?.PathItems != null ? new(callback?.PathItems) : null;
            Extensions = callback?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(callback.Extensions) : null;
        }
@@ -98,5 +99,11 @@ public void SerializeAsV2(IOpenApiWriter writer)
        {
            // Callback object does not exist in V2.
        }
+
+        /// <inheritdoc/>
+        public IOpenApiCallback CreateShallowCopy()
+        {
+            return new OpenApiCallback(this);
+        }
    }
 }
diff --git a/src/Microsoft.OpenApi/Models/OpenApiDocument.cs b/src/Microsoft.OpenApi/Models/OpenApiDocument.cs
@@ -587,43 +587,43 @@ public bool AddComponent<T>(string id, T componentToRegister)
            Components ??= new();
            switch (componentToRegister)
            {
-                case OpenApiSchema openApiSchema:
+                case IOpenApiSchema openApiSchema:
                    Components.Schemas ??= new Dictionary<string, IOpenApiSchema>();
                    Components.Schemas.Add(id, openApiSchema);
                    break;
-                case OpenApiParameter openApiParameter:
+                case IOpenApiParameter openApiParameter:
                    Components.Parameters ??= new Dictionary<string, IOpenApiParameter>();
                    Components.Parameters.Add(id, openApiParameter);
                    break;
-                case OpenApiResponse openApiResponse:
+                case IOpenApiResponse openApiResponse:
                    Components.Responses ??= new Dictionary<string, IOpenApiResponse>();
                    Components.Responses.Add(id, openApiResponse);
                    break;
-                case OpenApiRequestBody openApiRequestBody:
+                case IOpenApiRequestBody openApiRequestBody:
                    Components.RequestBodies ??= new Dictionary<string, IOpenApiRequestBody>();
                    Components.RequestBodies.Add(id, openApiRequestBody);
                    break;
-                case OpenApiLink openApiLink:
+                case IOpenApiLink openApiLink:
                    Components.Links ??= new Dictionary<string, IOpenApiLink>();
                    Components.Links.Add(id, openApiLink);
                    break;
-                case OpenApiCallback openApiCallback:
+                case IOpenApiCallback openApiCallback:
                    Components.Callbacks ??= new Dictionary<string, IOpenApiCallback>();
                    Components.Callbacks.Add(id, openApiCallback);
                    break;
-                case OpenApiPathItem openApiPathItem:
+                case IOpenApiPathItem openApiPathItem:
                    Components.PathItems ??= new Dictionary<string, IOpenApiPathItem>();
                    Components.PathItems.Add(id, openApiPathItem);
                    break;
-                case OpenApiExample openApiExample:
+                case IOpenApiExample openApiExample:
                    Components.Examples ??= new Dictionary<string, IOpenApiExample>();
                    Components.Examples.Add(id, openApiExample);
                    break;
-                case OpenApiHeader openApiHeader:
+                case IOpenApiHeader openApiHeader:
                    Components.Headers ??= new Dictionary<string, IOpenApiHeader>();
                    Components.Headers.Add(id, openApiHeader);
                    break;
-                case OpenApiSecurityScheme openApiSecurityScheme:
+                case IOpenApiSecurityScheme openApiSecurityScheme:
                    Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();
                    Components.SecuritySchemes.Add(id, openApiSecurityScheme);
                    break;

diff --git a/src/Microsoft.OpenApi/Models/OpenApiExample.cs b/src/Microsoft.OpenApi/Models/OpenApiExample.cs
@@ -39,7 +39,7 @@ public OpenApiExample() { }
        /// Initializes a copy of <see cref="OpenApiExample"/> object
        /// </summary>
        /// <param name="example">The <see cref="IOpenApiExample"/> object</param>
-        public OpenApiExample(IOpenApiExample example)
+        internal OpenApiExample(IOpenApiExample example)
        {
            Utils.CheckArgumentNull(example);
            Summary = example.Summary ?? Summary;
@@ -90,5 +90,11 @@ public void SerializeAsV2(IOpenApiWriter writer)
        {
            SerializeInternal(writer, OpenApiSpecVersion.OpenApi2_0);
        }
+
+        /// <inheritdoc/>
+        public IOpenApiExample CreateShallowCopy()
+        {
+            return new OpenApiExample(this);
+        }
    }
 }
diff --git a/src/Microsoft.OpenApi/Models/OpenApiHeader.cs b/src/Microsoft.OpenApi/Models/OpenApiHeader.cs
@@ -63,20 +63,21 @@ public OpenApiHeader() { }
        /// <summary>
        /// Initializes a copy of an <see cref="OpenApiHeader"/> object
        /// </summary>
-        public OpenApiHeader(IOpenApiHeader header)
+        internal OpenApiHeader(IOpenApiHeader header)
        {
-            Description = header?.Description ?? Description;
-            Required = header?.Required ?? Required;
-            Deprecated = header?.Deprecated ?? Deprecated;
-            AllowEmptyValue = header?.AllowEmptyValue ?? AllowEmptyValue;
-            Style = header?.Style ?? Style;
-            Explode = header?.Explode ?? Explode;
-            AllowReserved = header?.AllowReserved ?? AllowReserved;
-            Schema = header?.Schema != null ? new OpenApiSchema(header.Schema) : null;
-            Example = header?.Example != null ? JsonNodeCloneHelper.Clone(header.Example) : null;
-            Examples = header?.Examples != null ? new Dictionary<string, IOpenApiExample>(header.Examples) : null;
-            Content = header?.Content != null ? new Dictionary<string, OpenApiMediaType>(header.Content) : null;
-            Extensions = header?.Extensions != null ? new Dictionary<string, IOpenApiExtension>(header.Extensions) : null;
+            Utils.CheckArgumentNull(header);
+            Description = header.Description ?? Description;
+            Required = header.Required;
+            Deprecated = header.Deprecated;
+            AllowEmptyValue = header.AllowEmptyValue;
+            Style = header.Style ?? Style;
+            Explode = header.Explode;
+            AllowReserved = header.AllowReserved;
+            Schema = header.Schema.CreateShallowCopy();
+            Example = header.Example != null ? JsonNodeCloneHelper.Clone(header.Example) : null;
+            Examples = header.Examples != null ? new Dictionary<string, IOpenApiExample>(header.Examples) : null;
+            Content = header.Content != null ? new Dictionary<string, OpenApiMediaType>(header.Content) : null;
+            Extensions = header.Extensions != null ? new Dictionary<string, IOpenApiExtension>(header.Extensions) : null;
        }

        /// <summary>
@@ -187,5 +188,11 @@ public void SerializeAsV2(IOpenApiWriter writer)

            writer.WriteEndObject();
        }
+
+        /// <inheritdoc/>
+        public IOpenApiHeader CreateShallowCopy()
+        {
+            return new OpenApiHeader(this);
+        }
    }
 }
diff --git a/src/Microsoft.OpenApi/Models/OpenApiLink.cs b/src/Microsoft.OpenApi/Models/OpenApiLink.cs
@@ -43,7 +43,7 @@ public OpenApiLink() { }
        /// <summary>
        /// Initializes a copy of an <see cref="OpenApiLink"/> object
        /// </summary>
-        public OpenApiLink(IOpenApiLink link)
+        internal OpenApiLink(IOpenApiLink link)
        {
            Utils.CheckArgumentNull(link);
            OperationRef = link.OperationRef ?? OperationRef;
@@ -102,5 +102,11 @@ public void SerializeAsV2(IOpenApiWriter writer)
        {
            // Link object does not exist in V2.
        }
+
+        /// <inheritdoc/>
+        public IOpenApiLink CreateShallowCopy()
+        {
+            return new OpenApiLink(this);
+        }
    }
 }
diff --git a/src/Microsoft.OpenApi/Models/OpenApiMediaType.cs b/src/Microsoft.OpenApi/Models/OpenApiMediaType.cs
@@ -59,7 +59,7 @@ public OpenApiMediaType() { }
        /// </summary>
        public OpenApiMediaType(OpenApiMediaType? mediaType)
        {
-            Schema = mediaType?.Schema != null ? new OpenApiSchema(mediaType.Schema) : null;
+            Schema = mediaType?.Schema?.CreateShallowCopy();
            Example = mediaType?.Example != null ? JsonNodeCloneHelper.Clone(mediaType.Example) : null;
            Examples = mediaType?.Examples != null ? new Dictionary<string, IOpenApiExample>(mediaType.Examples) : null;
            Encoding = mediaType?.Encoding != null ? new Dictionary<string, OpenApiEncoding>(mediaType.Encoding) : null;