chore: merge main into current branch

Author: MaggieKimani1

.github/workflows/auto-merge-dependabot.yml

@@ -19,7 +19,7 @@ jobs:
     steps:
       - name: Dependabot metadata
         id: metadata
-        uses: dependabot/fetch-metadata@v2.3.0
+        uses: dependabot/fetch-metadata@v2.4.0
         with:
           github-token: "${{ secrets.GITHUB_TOKEN }}"
 

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.0.0-preview.17"
+  ".": "2.0.0-preview.20"
 }

CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [2.0.0-preview.20](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.19...v2.0.0-preview.20) (2025-05-20)
+
+
+### Bug Fixes
+
+* nullable and type ordering should be maintain to ease up migration work ([6c82aa6](https://github.com/microsoft/OpenAPI.NET/commit/6c82aa6b2d6e4f39af3c594edd8590a0cf749530))
+* nullable should not be inserted as an attempt to normalize the document ([6c82aa6](https://github.com/microsoft/OpenAPI.NET/commit/6c82aa6b2d6e4f39af3c594edd8590a0cf749530))
+* refactor to avoid adding duplicate entries ([41fd508](https://github.com/microsoft/OpenAPI.NET/commit/41fd508074f1b70415026df3aa878cd5f5e7b1ee))
+* refactor to avoid adding duplicate entries ([#2359](https://github.com/microsoft/OpenAPI.NET/issues/2359)) ([9791eb6](https://github.com/microsoft/OpenAPI.NET/commit/9791eb684a0f040feeb8c58701fd4f3577e73e2c))
+* tree node has the wrong structure because of trailing slashes ([2ffb273](https://github.com/microsoft/OpenAPI.NET/commit/2ffb2735aa3718370d6094186142f9cf50b194fa))
+* tree node has the wrong structure because of trailing slashes ([4439340](https://github.com/microsoft/OpenAPI.NET/commit/443934060e1e446de726addde69a2de955b95a7b))
+* wrong link to json schema spec in schema doc comments ([d9b0c90](https://github.com/microsoft/OpenAPI.NET/commit/d9b0c906f7173b81fea15001d588edcbc3eed8f1))
+* wrong link to json schema spec in schema doc comments ([9a73ec6](https://github.com/microsoft/OpenAPI.NET/commit/9a73ec6e5486d84b6a30a5fa0ac5961b381fc3d3))
+
+## [2.0.0-preview.19](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.18...v2.0.0-preview.19) (2025-05-16)
+
+
+### Bug Fixes
+
+* base url should be read from the settings when available ([f5d6e81](https://github.com/microsoft/OpenAPI.NET/commit/f5d6e81c21fd18b6de0fb19b535ad6dbc187790d))
+* base url should be read from the settings when available ([b17b7d8](https://github.com/microsoft/OpenAPI.NET/commit/b17b7d8d25fdf9a767411481287aacee31434aaa))
+* discriminator mapping references don't get a document when created from DOM ([767d3fb](https://github.com/microsoft/OpenAPI.NET/commit/767d3fb163b273b275cd67d710c573c59e4e642b))
+* discriminator mapping references don't get a document when created from DOM ([fdfe002](https://github.com/microsoft/OpenAPI.NET/commit/fdfe002d551fc3feaaeb5af24042826f13bdf412))
+
+## [2.0.0-preview.18](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.17...v2.0.0-preview.18) (2025-05-13)
+
+
+### Features
+
+* upgrades openapi.net.odata and apimanifest to the latest version ([80844a6](https://github.com/microsoft/OpenAPI.NET/commit/80844a60ae50ba0a4d54d7dd2e45ce8360206bf5))
+* upgrades openapi.net.odata and apimanifest to the latest version ([938a2e0](https://github.com/microsoft/OpenAPI.NET/commit/938a2e07b40b082e01ed1cdf3244767cbdca4061))
+
+
+### Bug Fixes
+
+* avoid calling virtual members in constructor ([5835057](https://github.com/microsoft/OpenAPI.NET/commit/5835057a7e905e371f859e727ddaf65ec08c6db0))
+* Fix typo in error message ([#2345](https://github.com/microsoft/OpenAPI.NET/issues/2345)) ([3f8b2b9](https://github.com/microsoft/OpenAPI.NET/commit/3f8b2b99c07bd3c58825728c2dd2ffed91d88fbe))
+* handle deserializing and writing empty security requirements [#1426](https://github.com/microsoft/OpenAPI.NET/issues/1426) ([#2323](https://github.com/microsoft/OpenAPI.NET/issues/2323)) ([962e0e4](https://github.com/microsoft/OpenAPI.NET/commit/962e0e436f96b1b68613013d75307dc1f92ce15c))
+* normalized override implementation for parameter types serialization in v2 ([5930916](https://github.com/microsoft/OpenAPI.NET/commit/593091621926defcbc2727a922613e34557d882a))
+
 ## [2.0.0-preview.17](https://github.com/microsoft/OpenAPI.NET/compare/v2.0.0-preview.16...v2.0.0-preview.17) (2025-04-16)
 
 

Directory.Build.props

@@ -12,7 +12,7 @@
     <PackageProjectUrl>https://github.com/Microsoft/OpenAPI.NET</PackageProjectUrl>
     <Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
     <PackageTags>OpenAPI .NET</PackageTags>
-    <Version>2.0.0-preview.17</Version>
+    <Version>2.0.0-preview.20</Version>
   </PropertyGroup>
   <!-- https://github.com/clairernovotny/DeterministicBuilds#deterministic-builds -->
   <PropertyGroup Condition="'$(TF_BUILD)' == 'true'">

docs/upgrade-guide-2.md

@@ -203,7 +203,7 @@ var openApiObject = new OpenApiObject
     }
 };
 var parameter = new OpenApiParameter();
-parameter.Extensions.Add("x-foo", new OpenApiAny(openApiObject));
+parameter.Extensions.Add("x-foo", openApiObject);
 
 ```
 
@@ -223,7 +223,7 @@ var openApiObject = new JsonObject
     }
 };
 var parameter = new OpenApiParameter();
-parameter.Extensions.Add("x-foo", new OpenApiAny(openApiObject));
+parameter.Extensions.Add("x-foo", new JsonNodeExtension(openApiObject));
 
 ```
 
@@ -361,6 +361,29 @@ public class OpenApiSchema : IMetadataContainer, IOpenApiExtensible, IOpenApiRef
 
 There are a number of new features in OpenAPI v3.1 that are now supported in OpenAPI.NET.
 
+### JsonSchema Dialect and BaseUri in OpenApiDocument
+To enable full compatibility with JSON Schema, the `OpenApiDocument` class now supports a `JsonSchemaDialect` property. This property specifies the JSON Schema dialect used throughout the document, using a URI. By explicitly declaring the dialect, tooling can be directed to use a JSON Schema version other than the default [2020-12 draft](https://json-schema.org/draft/2020-12/json-schema-core.html).  However, OpenAPI.NET does not guarantee compatibility with versions other than 2020-12.
+
+In addition, a `BaseUri` property has been added to represent the identity of the OpenAPI document. If the document’s identity is not provided or cannot be determined at based on its location, this property will be set to a generated placeholder URI.
+
+```csharp
+/// <summary>
+/// Describes an OpenAPI object (OpenAPI document). See: https://spec.openapis.org
+/// </summary>
+public class OpenApiDocument : IOpenApiSerializable, IOpenApiExtensible, IMetadataContainer
+{
+    /// <summary>
+    /// The default value for the $schema keyword within Schema Objects contained within this OAS document. This MUST be in the form of a URI.
+    /// </summary>
+    public Uri? JsonSchemaDialect { get; set; }
+
+    /// <summary>
+    /// Absolute location of the document or a generated placeholder if location is not given
+    /// </summary>
+    public Uri BaseUri { get; internal set; }
+}
+```
+
 ### Webhooks
 
 ```csharp
@@ -483,6 +506,7 @@ OpenApiComponents components = new OpenApiComponents
 ### OpenApiDocument.SerializeAs()
 
 The `SerializeAs()` method simplifies serialization scenarios, making it easier to convert OpenAPI documents to different formats.
+
 **Example:**
 
 ```csharp
@@ -493,7 +517,7 @@ string json = document.SerializeAs(OpenApiSpecVersion.OpenApi3_0, OpenApiConstan
 
 ### Use OpenApiConstants string Instead of OpenApiFormat Enum
 
-OpenApiConstants are now used instead of OpenApiFormat enums.
+`OpenApiConstants` are now used instead the `OpenApiFormat` enumeration.
 
 **Example:**
 
@@ -505,6 +529,133 @@ var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, Open
 var outputString = openApiDocument.Serialize(OpenApiSpecVersion.OpenApi2_0, OpenApiConstants.Json);
 ```
 
+### OpenApiSchema's Type property is now a flaggable enum
+
+In v2.0, the Type property in `OpenApiSchema` is now defined as a flaggable enum, allowing consumers to swap nullable for type arrays.
+
+**Example:**
+```csharp
+// v1.6.x
+var schema = new OpenApiSchema
+{
+    Type = "string",
+    Nullable = true
+}
+
+// v2.0
+// bitwise OR(|) - combines flags to allow multiple types
+var schema = new OpenApiSchema
+{
+    Type = JsonSchemaType.String | JsonSchemaType.Null 
+}
+
+// bitwise NOT(~) - inverts bits; filters out null flag
+var schema = new OpenApiSchema
+{
+    Type = JsonSchemaType.String & ~JsonSchemaType.Null
+}
+
+// bitwise AND(&) - intersects flags to check for a specific type
+var schema = new OpenApiSchema
+{
+    Type = (JsonSchemaType.String & JsonSchemaType.Null) == JsonSchemaType.Null 
+}
+
+```
+
+### Component registration in a document's workspace
+
+When loading up a file into an in-memory document, all the components contained in the document are registered within the document's workspace by default to aid with reference resolution.
+However if you're working directly with a DOM and you need the references resolved, you can register the components as below:
+
+```csharp
+// register all components
+document.Workspace.RegisterComponents(OpenApiDocument document);
+
+// register single component
+document.AddComponent<T>(string id, T componentToRegister);
+```
+
+### Refactored model architecture
+
+The following structural improvements have been made to the OpenAPI model layer to enhance type safety, extensibility, and maintainability:
+
+1. Model Interfaces Introduced:
+Each model now has a corresponding interface (e.g., `IOpenApiSchema` for `OpenApiSchema`). This allows for better abstraction and testing support, while also simplifying cross-cutting concerns like serialization.
+
+2. Models as Reference Types:
+All models are now implemented as reference types to ensure consistent identity semantics, especially when managing circular references or shared definitions.
+
+3. Type Assertion Pattern Adopted:
+A standardized pattern has been introduced for casting model instances to specific types safely and predictably, reducing the risk of invalid casts or reflection-based logic.
+
+4. Removed Reference Fields from Base Models:
+Properties like `Reference` that were previously defined on base model types have been removed. Models that support referencing now handle this behavior explicitly via composition rather than inheritance.
+
+5. New Target and RecursiveTarget Properties:
+A `Target` property that points to the actual resolved model instance as well as a `RecursiveTarget` property that handles recursive references and supports advanced dereferencing logic have been introduced.
+
+6. Removed OpenApiReferenceResolver:
+This resolver class has been removed in favor of a more streamlined resolution model using the `Target` and `RecursiveTarget` properties along with updated reader/serializer pipelines.
+
+### Visitor and Validator now pass an interface model
+
+**Example:**
+```csharp
+//v1.6.x
+public override void Visit(OpenApiParameter parameter){}
+
+//v2.0
+public override void Visit(IOpenApiParameter parameter){}
+```
+
+### Cleaned up the IEffective/GetEffective infrastructure
+
+All the `IEffective` and `GetEffective` infrastructure in the models have been removed as we've implemented lazy reference resolution using the proxy design.
+
+### Shallow Copy in place of copy constructors
+
+Copy constructors for referenceable components have been made internal, a new `CreateShallowCopy()` method has been exposed on these models to facilitate cloning.
+
+**Example:**
+```csharp
+var schema = new OpenApiSchema();
+var schemaCopy = schema.CreateShallowCopy();
+```
+
+### Duplicated _style Property on Parameter Removed
+
+The redundant _style property on the Parameter model has been removed to simplify the model's structure.
+
+### Discriminator now use References
+
+Discriminator mappings have been updated from using a `Dictionary<string, string>` to a `Dictionary<string, OpenApiSchemaReference>`. This change improves the handling of discriminator mappings by referencing OpenAPI schema components more explicitly, which enhances schema resolution.
+
+**Example:**
+```csharp
+// v1.6.x
+Discriminator = new()
+{
+    PropertyName = "@odata.type",
+    Mapping = new Dictionary<string, string> {
+        {
+            "#microsoft.graph.directoryObject", "#/components/schemas/microsoft.graph.directoryObject"
+        }
+    }
+}
+
+//v2.0
+Discriminator = new()
+{
+    PropertyName = "@odata.type",
+    Mapping = new Dictionary<string, OpenApiSchemaReference> {
+        {
+            "#microsoft.graph.directoryObject", new OpenApiSchemaReference("microsoft.graph.directoryObject")
+        }
+    }
+}
+```
+
 ### Bug Fixes
 
 ## Serialization of References
@@ -524,17 +675,3 @@ OpenApiSchemaReference schemaRef = new OpenApiSchemaReference("MySchema")
 
 If you have any feedback please file a GitHub issue [here](https://github.com/microsoft/OpenAPI.NET/issues)
 The team is looking forward to hear your experience trying the new version and we hope you have fun busting out your OpenAPI 3.1 descriptions.
-
-## Todos
-
-- Models now have matching interfaces + reference type + type assertion pattern + reference fields removed from the base model + Target + RecursiveTarget + removed OpenApiReferenceResolver.
-- Workspace + component resolution.
-- Visitor and Validator method now pass the interface model.
-- Removed all the IEffective/GetEffective infrastructure.
-- OpenApiSchema.Type is now a flag enum + bitwise operations.
-- JsonSchemaDialect + BaseUri in document.
-- Copy constructors are gone, use shallow copy method.
-- Multiple methods that should have been internal have been changed from public to private link OpenApiLink.SerializeAsV3WithoutReference.
-- duplicated _style property on parameter was removed.
-- discriminator now uses references.
-- ValidationRuleSet now accepts a key?

performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report-github.md

@@ -1,18 +1,18 @@
 ```
 
-BenchmarkDotNet v0.14.0, Windows 11 (10.0.26100.3476)
+BenchmarkDotNet v0.14.0, Windows 11 (10.0.26100.3981)
 11th Gen Intel Core i7-1185G7 3.00GHz, 1 CPU, 8 logical and 4 physical cores
-.NET SDK 8.0.408
-  [Host]   : .NET 8.0.15 (8.0.1525.16413), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
-  ShortRun : .NET 8.0.15 (8.0.1525.16413), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
+.NET SDK 8.0.409
+  [Host]   : .NET 8.0.16 (8.0.1625.21506), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
+  ShortRun : .NET 8.0.16 (8.0.1625.21506), X64 RyuJIT AVX-512F+CD+BW+DQ+VL+VBMI
 
 Job=ShortRun  IterationCount=3  LaunchCount=1  
 WarmupCount=3  
 
 ```
 | Method       | Mean         | Error         | StdDev       | Gen0       | Gen1       | Gen2      | Allocated    |
 |------------- |-------------:|--------------:|-------------:|-----------:|-----------:|----------:|-------------:|
-| PetStoreYaml |     450.5 μs |      59.26 μs |      3.25 μs |    58.5938 |    11.7188 |         - |    377.15 KB |
-| PetStoreJson |     172.8 μs |     123.46 μs |      6.77 μs |    39.0625 |     7.8125 |         - |    239.29 KB |
-| GHESYaml     | 943,452.7 μs | 137,685.49 μs |  7,547.01 μs | 66000.0000 | 21000.0000 | 3000.0000 | 389463.91 KB |
-| GHESJson     | 468,401.8 μs | 300,711.80 μs | 16,483.03 μs | 41000.0000 | 15000.0000 | 3000.0000 | 250934.62 KB |
+| PetStoreYaml |     470.3 μs |     138.05 μs |      7.57 μs |    58.5938 |    11.7188 |         - |    380.53 KB |
+| PetStoreJson |     166.0 μs |      43.84 μs |      2.40 μs |    39.0625 |     8.7891 |         - |    242.67 KB |
+| GHESYaml     | 915,406.4 μs | 714,492.62 μs | 39,163.75 μs | 68000.0000 | 22000.0000 | 4000.0000 | 395800.98 KB |
+| GHESJson     | 470,609.4 μs | 264,698.88 μs | 14,509.04 μs | 42000.0000 | 15000.0000 | 3000.0000 | 257270.45 KB |

performance/benchmark/BenchmarkDotNet.Artifacts/results/performance.Descriptions-report.csv

@@ -1,5 +1,5 @@
 Method,Job,AnalyzeLaunchVariance,EvaluateOverhead,MaxAbsoluteError,MaxRelativeError,MinInvokeCount,MinIterationTime,OutlierMode,Affinity,EnvironmentVariables,Jit,LargeAddressAware,Platform,PowerPlanMode,Runtime,AllowVeryLargeObjects,Concurrent,CpuGroups,Force,HeapAffinitizeMask,HeapCount,NoAffinitize,RetainVm,Server,Arguments,BuildConfiguration,Clock,EngineFactory,NuGetReferences,Toolchain,IsMutator,InvocationCount,IterationCount,IterationTime,LaunchCount,MaxIterationCount,MaxWarmupIterationCount,MemoryRandomization,MinIterationCount,MinWarmupIterationCount,RunStrategy,UnrollFactor,WarmupCount,Mean,Error,StdDev,Gen0,Gen1,Gen2,Allocated
-PetStoreYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,450.5 μs,59.26 μs,3.25 μs,58.5938,11.7188,0.0000,377.15 KB
-PetStoreJson,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,172.8 μs,123.46 μs,6.77 μs,39.0625,7.8125,0.0000,239.29 KB
-GHESYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"943,452.7 μs","137,685.49 μs","7,547.01 μs",66000.0000,21000.0000,3000.0000,389463.91 KB
-GHESJson,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"468,401.8 μs","300,711.80 μs","16,483.03 μs",41000.0000,15000.0000,3000.0000,250934.62 KB
+PetStoreYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,470.3 μs,138.05 μs,7.57 μs,58.5938,11.7188,0.0000,380.53 KB
+PetStoreJson,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,166.0 μs,43.84 μs,2.40 μs,39.0625,8.7891,0.0000,242.67 KB
+GHESYaml,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"915,406.4 μs","714,492.62 μs","39,163.75 μs",68000.0000,22000.0000,4000.0000,395800.98 KB
+GHESJson,ShortRun,False,Default,Default,Default,Default,Default,Default,11111111,Empty,RyuJit,Default,X64,8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c,.NET 8.0,False,True,False,True,Default,Default,False,False,False,Default,Default,Default,Default,Default,Default,Default,Default,3,Default,1,Default,Default,Default,Default,Default,Default,16,3,"470,609.4 μs","264,698.88 μs","14,509.04 μs",42000.0000,15000.0000,3000.0000,257270.45 KB