feat/one one support

README.md

@@ -2,7 +2,7 @@
 
 # OpenAPI Overlay Library & CLI for dotnet
 
-This project provides a .NET implementation of the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/latest.html), allowing you to dynamically apply overlays (patches) to existing OpenAPI documents (v3.0+), following the official OpenAPI Overlay 1.0.0 specification.
+This project provides a .NET implementation of the [OpenAPI Overlay Specification](https://spec.openapis.org/overlay/latest.html), allowing you to dynamically apply overlays (patches) to existing OpenAPI documents (v3.0+), following the official OpenAPI Overlay 1.0.0 and 1.1.0 specification.
 
 The library enables developers to programmatically apply overlays, validate them, and generate updated OpenAPI documents without relying on third-party tools like Swagger.
 
@@ -112,17 +112,7 @@ var jsonResult = textWriter.ToString();
 
 This library implements the following experimental features:
 
-### Copy
-
-The [copy proposal](https://github.com/OAI/Overlay-Specification/pull/150) to the Overlay specification works similarly to the update action, except it sources its value from another node. This library adds a property under an experimental flag, serializes and deserializes the value, and applies a copy overlay to an OpenAPI document.
-
-```json
-{
-    "target": "$.info.title",
-    "description": "Copy description to title",
-    "x-copy": "$.info.description"
-}
-```
+No experimental features are implemented at this moment.
 
 ## Release notes
 

src/lib/Interfaces/IOverlayReader.cs

@@ -16,11 +16,10 @@ public interface IOverlayReader
     /// Async method to read the stream and parse it into an OpenAPI document.  
     /// </summary>  
     /// <param name="input">The stream input.</param>  
-    /// <param name="location">Location of where the document that is getting loaded is saved.</param>  
     /// <param name="settings">The OpenApi reader settings.</param>  
     /// <param name="cancellationToken">Propagates notification that an operation should be canceled.</param>  
     /// <returns>A task that represents the asynchronous operation, containing the read result.</returns>  
-    Task<ReadResult> ReadAsync(Stream input, Uri location, OverlayReaderSettings settings, CancellationToken cancellationToken = default);
+    Task<ReadResult> ReadAsync(Stream input, OverlayReaderSettings settings, CancellationToken cancellationToken = default);
 
     /// <summary>  
     /// Reads the stream and returns a JsonNode representation of the input.

src/lib/Interfaces/IOverlaySerializable.cs

@@ -5,11 +5,20 @@ namespace BinkyLabs.OpenApi.Overlays;
 /// <summary>
 /// Represents an OpenAPI overlay element that comes with serialization functionality.
 /// </summary>
+/// <remarks>
+/// This interface defines methods for serializing an object to different versions of the OpenAPI Overlay specification.
+/// This interface should only be implemented by this library, and not by external consumers as we will add new methods without bumping major versions which will lead to source breaking changes.
+/// </remarks>
 public interface IOverlaySerializable
 {
     /// <summary>
     /// Serializes the object to the OpenAPI Overlay v1 format.
     /// </summary>
     /// <param name="writer">A Microsoft.OpenAPI writer</param>
     void SerializeAsV1(IOpenApiWriter writer);
+    /// <summary>
+    /// Serializes the object to the OpenAPI Overlay v1.1 format.
+    /// </summary>
+    /// <param name="writer">A Microsoft.OpenAPI writer</param>
+    void SerializeAsV1_1(IOpenApiWriter writer);
 }

src/lib/Interfaces/IOverlayVersionService.cs

@@ -24,7 +24,6 @@ internal interface IOverlayVersionService
     /// Converts a generic RootNode instance into a strongly typed OverlayDocument
     /// </summary>
     /// <param name="rootNode">RootNode containing the information to be converted into an OpenAPI Document</param>
-    /// <param name="location">Location of where the document that is getting loaded is saved</param>
     /// <returns>Instance of OverlayDocument populated with data from rootNode</returns>
-    OverlayDocument LoadDocument(RootNode rootNode, Uri location);
+    OverlayDocument LoadDocument(RootNode rootNode);
 }

src/lib/Models/OverlayAction.cs

@@ -40,20 +40,17 @@ public class OverlayAction : IOverlaySerializable, IOverlayExtensible
     /// <summary>
     /// A string value that indicates that the target object or array MUST be copied to the location indicated by this string, which MUST be a JSON Pointer.
     /// This field is mutually exclusive with the <see cref="Remove"/> and <see cref="Update"/> fields.
-    /// This field is experimental and not part of the OpenAPI Overlay specification v1.0.0.
-    /// This field is an implementation of <see href="https://github.com/OAI/Overlay-Specification/pull/150">the copy proposal</see>.
     /// </summary>
-    [Experimental("BOO001", UrlFormat = "https://github.com/OAI/Overlay-Specification/pull/150")]
     public string? Copy { get; set; }
 
     /// <inheritdoc/>
     public IDictionary<string, IOverlayExtension>? Extensions { get; set; }
 
-    /// <summary>
-    /// Serializes the action object as an OpenAPI Overlay v1.0.0 JSON object.
-    /// </summary>
-    /// <param name="writer">The OpenAPI writer to use for serialization.</param>
-    public void SerializeAsV1(IOpenApiWriter writer)
+    /// <inheritdoc/>
+    public void SerializeAsV1(IOpenApiWriter writer) => SerializeInternal(writer, OverlaySpecVersion.Overlay1_0, "x-copy");
+    /// <inheritdoc/>
+    public void SerializeAsV1_1(IOpenApiWriter writer) => SerializeInternal(writer, OverlaySpecVersion.Overlay1_1, "copy");
+    private void SerializeInternal(IOpenApiWriter writer, OverlaySpecVersion version, string copyFieldName)
     {
         writer.WriteStartObject();
         writer.WriteRequiredProperty("target", Target);
@@ -64,19 +61,15 @@ public void SerializeAsV1(IOpenApiWriter writer)
         {
             writer.WriteOptionalObject("update", Update, (w, s) => w.WriteAny(s));
         }
-#pragma warning disable BOO001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
         if (Copy != null)
         {
-            writer.WriteProperty("x-copy", Copy);
+            writer.WriteProperty(copyFieldName, Copy);
         }
-#pragma warning restore BOO001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
 
-        writer.WriteOverlayExtensions(Extensions, OverlaySpecVersion.Overlay1_0);
+        writer.WriteOverlayExtensions(Extensions, version);
         writer.WriteEndObject();
     }
 
-#pragma warning disable BOO001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-
     private (bool, JsonPath?, PathResult?) ValidateBeforeApplying(JsonNode documentJsonNode, OverlayDiagnostic overlayDiagnostic, int index)
     {
         if (string.IsNullOrEmpty(Target))
@@ -193,7 +186,6 @@ private bool CopyNodes(PathResult parseResult, JsonNode documentJsonNode, Overla
         }
         return true;
     }
-#pragma warning restore BOO001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
 
     private static string GetPointer(int index) => $"$.actions[{index}]";
 

src/lib/Models/OverlayDocument.cs

@@ -15,9 +15,9 @@ namespace BinkyLabs.OpenApi.Overlays;
 public class OverlayDocument : IOverlaySerializable, IOverlayExtensible
 {
     /// <summary>
-    /// Gets or sets the overlay version. Default is "1.0.0".
+    /// Gets or sets the overlay version. Default is "1.1.0".
     /// </summary>
-    public string? Overlay { get; internal set; } = "1.0.0";
+    public string? Overlay { get; internal set; } = "1.1.0";
 
     /// <summary>
     /// Gets or sets the overlay info object.
@@ -37,26 +37,31 @@ public class OverlayDocument : IOverlaySerializable, IOverlayExtensible
     /// <inheritdoc/>
     public IDictionary<string, IOverlayExtension>? Extensions { get; set; }
 
-    /// <summary>
-    /// Serializes the overlay document as an OpenAPI Overlay v1.0.0 JSON object.
-    /// </summary>
-    /// <param name="writer">The OpenAPI writer to use for serialization.</param>
-    public void SerializeAsV1(IOpenApiWriter writer)
+    /// <inheritdoc/>
+    public void SerializeAsV1(IOpenApiWriter writer) => SerializeInternal(writer, OverlaySpecVersion.Overlay1_0, (w, obj) => obj.SerializeAsV1(w));
+    /// <inheritdoc/>
+    public void SerializeAsV1_1(IOpenApiWriter writer) => SerializeInternal(writer, OverlaySpecVersion.Overlay1_1, (w, obj) => obj.SerializeAsV1_1(w));
+    private void SerializeInternal(IOpenApiWriter writer, OverlaySpecVersion version, Action<IOpenApiWriter, IOverlaySerializable> serializeAction)
     {
         writer.WriteStartObject();
-        writer.WriteRequiredProperty("overlay", "1.0.0");
+        writer.WriteRequiredProperty("overlay", SpecVersionToStringMap[version]);
         if (Info != null)
         {
-            writer.WriteRequiredObject("info", Info, (w, obj) => obj.SerializeAsV1(w));
+            writer.WriteRequiredObject("info", Info, serializeAction);
         }
         writer.WriteProperty("extends", Extends);
         if (Actions != null)
         {
-            writer.WriteRequiredCollection<OverlayAction>("actions", Actions, (w, action) => action.SerializeAsV1(w));
+            writer.WriteRequiredCollection<OverlayAction>("actions", Actions, serializeAction);
         }
-        writer.WriteOverlayExtensions(Extensions, OverlaySpecVersion.Overlay1_0);
+        writer.WriteOverlayExtensions(Extensions, version);
         writer.WriteEndObject();
     }
+    private static readonly Dictionary<OverlaySpecVersion, string> SpecVersionToStringMap = new()
+    {
+        { OverlaySpecVersion.Overlay1_0, "1.0.0" },
+        { OverlaySpecVersion.Overlay1_1, "1.1.0" },
+    };
 
     /// <summary>
     /// Parses a local file path or Url into an Open API document.

src/lib/Models/OverlayInfo.cs

@@ -19,19 +19,32 @@ public class OverlayInfo : IOverlaySerializable, IOverlayExtensible
     /// </summary>
     public string? Version { get; set; }
 
+    /// <summary>
+    /// Gets or sets the description of the overlay.
+    /// </summary>
+    public string? Description { get; set; }
+
     /// <inheritdoc/>
     public IDictionary<string, IOverlayExtension>? Extensions { get; set; }
 
-    /// <summary>
-    /// Serializes the info object as an OpenAPI Overlay v1.0.0 JSON object.
-    /// </summary>
-    /// <param name="writer">The OpenAPI writer to use for serialization.</param>
-    public void SerializeAsV1(IOpenApiWriter writer)
+    /// <inheritdoc/>
+    public void SerializeAsV1(IOpenApiWriter writer) => SerializeInternal(writer, OverlaySpecVersion.Overlay1_0);
+    /// <inheritdoc/>
+    public void SerializeAsV1_1(IOpenApiWriter writer) => SerializeInternal(writer, OverlaySpecVersion.Overlay1_1);
+    private void SerializeInternal(IOpenApiWriter writer, OverlaySpecVersion version)
     {
         writer.WriteStartObject();
         writer.WriteProperty("title", Title);
         writer.WriteProperty("version", Version);
-        writer.WriteOverlayExtensions(Extensions, OverlaySpecVersion.Overlay1_0);
+
+        // Handle version-specific description field name
+        if (Description != null)
+        {
+            var descriptionFieldName = version == OverlaySpecVersion.Overlay1_0 ? "x-description" : "description";
+            writer.WriteProperty(descriptionFieldName, Description);
+        }
+
+        writer.WriteOverlayExtensions(Extensions, version);
         writer.WriteEndObject();
     }
 }

src/lib/Models/OverlayVersion.cs

@@ -11,4 +11,9 @@ public enum OverlaySpecVersion
     /// See: https://spec.openapis.org/overlay/v1.0.0.html
     /// </summary>
     Overlay1_0 = 1,
+    /// <summary>
+    /// The OpenAPI Overlay version 1.1.0
+    /// See: https://spec.openapis.org/overlay/v1.1.0.html
+    /// </summary>
+    Overlay1_1 = 2
 }

src/lib/PublicAPI.Unshipped.txt

@@ -6,9 +6,10 @@ BinkyLabs.OpenApi.Overlays.IOverlayExtension
 BinkyLabs.OpenApi.Overlays.IOverlayExtension.Write(Microsoft.OpenApi.IOpenApiWriter! writer, BinkyLabs.OpenApi.Overlays.OverlaySpecVersion specVersion) -> void
 BinkyLabs.OpenApi.Overlays.IOverlayReader
 BinkyLabs.OpenApi.Overlays.IOverlayReader.GetJsonNodeFromStreamAsync(System.IO.Stream! input, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Text.Json.Nodes.JsonNode?>!
-BinkyLabs.OpenApi.Overlays.IOverlayReader.ReadAsync(System.IO.Stream! input, System.Uri! location, BinkyLabs.OpenApi.Overlays.OverlayReaderSettings! settings, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<BinkyLabs.OpenApi.Overlays.ReadResult!>!
+BinkyLabs.OpenApi.Overlays.IOverlayReader.ReadAsync(System.IO.Stream! input, BinkyLabs.OpenApi.Overlays.OverlayReaderSettings! settings, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<BinkyLabs.OpenApi.Overlays.ReadResult!>!
 BinkyLabs.OpenApi.Overlays.IOverlaySerializable
 BinkyLabs.OpenApi.Overlays.IOverlaySerializable.SerializeAsV1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
+BinkyLabs.OpenApi.Overlays.IOverlaySerializable.SerializeAsV1_1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
 BinkyLabs.OpenApi.Overlays.JsonNodeExtension
 BinkyLabs.OpenApi.Overlays.JsonNodeExtension.JsonNodeExtension(System.Text.Json.Nodes.JsonNode! jsonNode) -> void
 BinkyLabs.OpenApi.Overlays.JsonNodeExtension.Node.get -> System.Text.Json.Nodes.JsonNode!
@@ -24,6 +25,7 @@ BinkyLabs.OpenApi.Overlays.OverlayAction.OverlayAction() -> void
 BinkyLabs.OpenApi.Overlays.OverlayAction.Remove.get -> bool?
 BinkyLabs.OpenApi.Overlays.OverlayAction.Remove.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayAction.SerializeAsV1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
+BinkyLabs.OpenApi.Overlays.OverlayAction.SerializeAsV1_1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
 BinkyLabs.OpenApi.Overlays.OverlayAction.Target.get -> string?
 BinkyLabs.OpenApi.Overlays.OverlayAction.Target.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayAction.Update.get -> System.Text.Json.Nodes.JsonNode?
@@ -66,6 +68,7 @@ BinkyLabs.OpenApi.Overlays.OverlayDocument.Info.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayDocument.Overlay.get -> string?
 BinkyLabs.OpenApi.Overlays.OverlayDocument.OverlayDocument() -> void
 BinkyLabs.OpenApi.Overlays.OverlayDocument.SerializeAsV1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
+BinkyLabs.OpenApi.Overlays.OverlayDocument.SerializeAsV1_1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
 BinkyLabs.OpenApi.Overlays.OverlayException
 BinkyLabs.OpenApi.Overlays.OverlayException.OverlayException() -> void
 BinkyLabs.OpenApi.Overlays.OverlayException.OverlayException(string! message) -> void
@@ -74,18 +77,21 @@ BinkyLabs.OpenApi.Overlays.OverlayException.Pointer.get -> string?
 BinkyLabs.OpenApi.Overlays.OverlayException.Pointer.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayExtensibleExtensions
 BinkyLabs.OpenApi.Overlays.OverlayInfo
+BinkyLabs.OpenApi.Overlays.OverlayInfo.Description.get -> string?
+BinkyLabs.OpenApi.Overlays.OverlayInfo.Description.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayInfo.Extensions.get -> System.Collections.Generic.IDictionary<string!, BinkyLabs.OpenApi.Overlays.IOverlayExtension!>?
 BinkyLabs.OpenApi.Overlays.OverlayInfo.Extensions.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayInfo.OverlayInfo() -> void
 BinkyLabs.OpenApi.Overlays.OverlayInfo.SerializeAsV1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
+BinkyLabs.OpenApi.Overlays.OverlayInfo.SerializeAsV1_1(Microsoft.OpenApi.IOpenApiWriter! writer) -> void
 BinkyLabs.OpenApi.Overlays.OverlayInfo.Title.get -> string?
 BinkyLabs.OpenApi.Overlays.OverlayInfo.Title.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayInfo.Version.get -> string?
 BinkyLabs.OpenApi.Overlays.OverlayInfo.Version.set -> void
 BinkyLabs.OpenApi.Overlays.OverlayJsonReader
 BinkyLabs.OpenApi.Overlays.OverlayJsonReader.GetJsonNodeFromStreamAsync(System.IO.Stream! input, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Text.Json.Nodes.JsonNode?>!
 BinkyLabs.OpenApi.Overlays.OverlayJsonReader.OverlayJsonReader() -> void
-BinkyLabs.OpenApi.Overlays.OverlayJsonReader.ReadAsync(System.IO.Stream! input, System.Uri! location, BinkyLabs.OpenApi.Overlays.OverlayReaderSettings! settings, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<BinkyLabs.OpenApi.Overlays.ReadResult!>!
+BinkyLabs.OpenApi.Overlays.OverlayJsonReader.ReadAsync(System.IO.Stream! input, BinkyLabs.OpenApi.Overlays.OverlayReaderSettings! settings, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<BinkyLabs.OpenApi.Overlays.ReadResult!>!
 BinkyLabs.OpenApi.Overlays.OverlayReaderException
 BinkyLabs.OpenApi.Overlays.OverlayReaderException.OverlayReaderException() -> void
 BinkyLabs.OpenApi.Overlays.OverlayReaderException.OverlayReaderException(string! message) -> void
@@ -104,10 +110,11 @@ BinkyLabs.OpenApi.Overlays.OverlayReaderSettings.Readers.init -> void
 BinkyLabs.OpenApi.Overlays.OverlayReaderSettings.TryAddReader(string! format, BinkyLabs.OpenApi.Overlays.IOverlayReader! reader) -> bool
 BinkyLabs.OpenApi.Overlays.OverlaySpecVersion
 BinkyLabs.OpenApi.Overlays.OverlaySpecVersion.Overlay1_0 = 1 -> BinkyLabs.OpenApi.Overlays.OverlaySpecVersion
+BinkyLabs.OpenApi.Overlays.OverlaySpecVersion.Overlay1_1 = 2 -> BinkyLabs.OpenApi.Overlays.OverlaySpecVersion
 BinkyLabs.OpenApi.Overlays.OverlayYamlReader
 BinkyLabs.OpenApi.Overlays.OverlayYamlReader.GetJsonNodeFromStreamAsync(System.IO.Stream! input, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<System.Text.Json.Nodes.JsonNode?>!
 BinkyLabs.OpenApi.Overlays.OverlayYamlReader.OverlayYamlReader() -> void
-BinkyLabs.OpenApi.Overlays.OverlayYamlReader.ReadAsync(System.IO.Stream! input, System.Uri! location, BinkyLabs.OpenApi.Overlays.OverlayReaderSettings! settings, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<BinkyLabs.OpenApi.Overlays.ReadResult!>!
+BinkyLabs.OpenApi.Overlays.OverlayYamlReader.ReadAsync(System.IO.Stream! input, BinkyLabs.OpenApi.Overlays.OverlayReaderSettings! settings, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<BinkyLabs.OpenApi.Overlays.ReadResult!>!
 BinkyLabs.OpenApi.Overlays.Reader.OverlayDiagnostic
 BinkyLabs.OpenApi.Overlays.Reader.OverlayDiagnostic.Errors.get -> System.Collections.Generic.IList<Microsoft.OpenApi.OpenApiError!>!
 BinkyLabs.OpenApi.Overlays.Reader.OverlayDiagnostic.Errors.set -> void
@@ -127,7 +134,7 @@ BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.ExtensionParsers.get -> System.
 BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.ExtensionParsers.set -> void
 BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.GetFromTempStorage<T>(string! key, object? scope = null) -> T?
 BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.GetLocation() -> string!
-BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.Parse(System.Text.Json.Nodes.JsonNode! jsonNode, System.Uri! location) -> BinkyLabs.OpenApi.Overlays.OverlayDocument!
+BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.Parse(System.Text.Json.Nodes.JsonNode! jsonNode) -> BinkyLabs.OpenApi.Overlays.OverlayDocument!
 BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.ParseFragment<T>(System.Text.Json.Nodes.JsonNode! jsonNode, BinkyLabs.OpenApi.Overlays.OverlaySpecVersion version) -> T?
 BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.ParsingContext(BinkyLabs.OpenApi.Overlays.Reader.OverlayDiagnostic! diagnostic) -> void
 BinkyLabs.OpenApi.Overlays.Reader.ParsingContext.PopLoop(string! loopid) -> void