Merge branch 'main' into chore/upstream-sync

Signed-off-by: Vincent Biret <vibiret@microsoft.com>

Author: baywet

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.3.6"
+  ".": "2.3.7"
 }

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [2.3.7](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.6...v2.3.7) (2025-10-24)
+
+
+### Bug Fixes
+
+* adds a null value sentinel to enable roundtrip serializations of JsonNode typed properties ([337c6eb](https://github.com/microsoft/OpenAPI.NET/commit/337c6eb08a9cc99bfbe2cd08fed61678030b8b8b))
+* adds a null value sentinel to enable roundtrip serializations of JsonNode typed properties ([63b2b98](https://github.com/microsoft/OpenAPI.NET/commit/63b2b98b64633fdef3b7fafee882060a3e0808fd))
+* fixes a bug where yaml null values would end up as a string "null" during roundtrip serialization ([6e62de2](https://github.com/microsoft/OpenAPI.NET/commit/6e62de205f0a5d58b385b4536dc30035a9977054))
+* fixes a bug where yaml null values would end up as a string "null" during roundtrip serialization ([994184b](https://github.com/microsoft/OpenAPI.NET/commit/994184b41bcd433a078cdeef75ba43d92b6b9762))
+* YamlConverter adding extra quotes to string values when converting from JSON to YAML ([ccfebc8](https://github.com/microsoft/OpenAPI.NET/commit/ccfebc828c2793b00faf3d5b12bd95bc68901104))
+
+
+### Performance Improvements
+
+* do not duplicate nodes when indexing ([dbbbf13](https://github.com/microsoft/OpenAPI.NET/commit/dbbbf1330934bc35fb35610a6a5db65514596c48))
+* only initialize map node nodes on demand ([bdb5264](https://github.com/microsoft/OpenAPI.NET/commit/bdb5264bc41b345f9ea95924ca5ab679178b82b6))
+* reduce allocations in mapnode ([f58aad2](https://github.com/microsoft/OpenAPI.NET/commit/f58aad235f904f94704aa14700aaca4ac16205af))
+* removes the lazy initialization since the node is always enumerated ([1c96521](https://github.com/microsoft/OpenAPI.NET/commit/1c96521c82cfa7414602e4f4da64e629b6c69c29))
+* switches to lazy instantiation ([d3c758b](https://github.com/microsoft/OpenAPI.NET/commit/d3c758b0d4421d1da9979587dfaee91bbdee0c7c))
+* use deep equals for comparison to reduce allocations ([6ce3214](https://github.com/microsoft/OpenAPI.NET/commit/6ce3214ad3beb5abe6045e5aa1743db4249c1974))
+
 ## [2.3.6](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.5...v2.3.6) (2025-10-20)
 
 

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.3.6</Version>
+    <Version>2.3.7</Version>
   </PropertyGroup>
   <!-- https://github.com/clairernovotny/DeterministicBuilds#deterministic-builds -->
   <PropertyGroup Condition="'$(TF_BUILD)' == 'true'">

performance/resultsComparer/handlers/CompareCommandHandler.cs

@@ -64,7 +64,7 @@ private static async Task<int> CompareResultsAsync(string existingReportPath, st
             {
                 if (!comparisonPolicy.Equals(existingBenchmarkResult.Value, newBenchmarkResult))
                 {
-                    logger.LogError("Benchmark result for {ExistingBenchmarkResultKey} does not match the existing benchmark result. {ErrorMessage}", existingBenchmarkResult.Key, comparisonPolicy.GetErrorMessage(existingBenchmarkResult.Value, newBenchmarkResult));
+                    logger.LogError("Benchmark result for {ExistingBenchmarkResultKey} does not match the existing benchmark result (original!=new). {ErrorMessage}", existingBenchmarkResult.Key, comparisonPolicy.GetErrorMessage(existingBenchmarkResult.Value, newBenchmarkResult));
                     hasErrors = true;
                 }
             }

performance/resultsComparer/policies/PercentageMemoryUsagePolicy.cs

@@ -56,18 +56,18 @@ public override bool Equals(BenchmarkMemory? x, BenchmarkMemory? y)
     }
     private static double GetPercentageDifference(BenchmarkMemory x, BenchmarkMemory y)
     {
-        return Math.Truncate(Math.Abs(GetAbsoluteRatio(x, y)) * 10000) / 100;
+        return Math.Truncate(Math.Abs(GetRatio(x, y)) * 10000) / 100;
     }
-    private static double GetAbsoluteRatio(BenchmarkMemory x, BenchmarkMemory y)
+    private static double GetRatio(BenchmarkMemory x, BenchmarkMemory y)
     {
-        return Math.Abs(((double)(x.AllocatedBytes - y.AllocatedBytes))/x.AllocatedBytes);
+        return (double)(y.AllocatedBytes - x.AllocatedBytes) / x.AllocatedBytes;
     }
     public override string GetErrorMessage(BenchmarkMemory? x, BenchmarkMemory? y)
     {
         if (x is null || y is null)
         {
             return "One of the benchmarks is null.";
         }
-        return $"Allocated bytes differ: {x.AllocatedBytes} != {y.AllocatedBytes}, Ratio: {GetAbsoluteRatio(x, y)}, Allowed: {TolerancePercentagePoints}%";
+        return $"Allocated bytes differ: {x.AllocatedBytes} != {y.AllocatedBytes}, Ratio: {GetRatio(x, y)}, Allowed: {TolerancePercentagePoints}%";
     }
 }

src/Microsoft.OpenApi.Hidi/Microsoft.OpenApi.Hidi.csproj

@@ -38,7 +38,7 @@
       <PrivateAssets>all</PrivateAssets>
     </PackageReference>
     <PackageReference Include="System.CommandLine" Version="2.0.0-beta5.25306.1" />
-    <PackageReference Include="Microsoft.OData.Edm" Version="8.4.0" />
+    <PackageReference Include="Microsoft.OData.Edm" Version="8.4.2" />
     <PackageReference Include="Microsoft.OpenApi.OData" Version="2.0.0" />
     <PackageReference Include="Microsoft.OpenApi.ApiManifest" Version="2.0.0-preview5" />
     <PackageReference Include="System.CommandLine.Hosting" Version="0.4.0-alpha.25306.1" />

src/Microsoft.OpenApi.YamlReader/OpenApiYamlReader.cs

@@ -131,9 +131,9 @@ static JsonNode LoadJsonNodesFromYamlDocument(TextReader input)
         {
             var yamlStream = new YamlStream();
             yamlStream.Load(input);
-            if (yamlStream.Documents.Any())
+            if (yamlStream.Documents.Any() && yamlStream.Documents[0].ToJsonNode() is { } jsonNode)
             {
-                return yamlStream.Documents[0].ToJsonNode();
+                return jsonNode;
             }
 
             throw new InvalidOperationException("No documents found in the YAML stream.");

src/Microsoft.OpenApi.YamlReader/YamlConverter.cs

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using System.Globalization;
 using System.Linq;
+using System.Text.Json;
 using System.Text.Json.Nodes;
 using SharpYaml;
 using SharpYaml.Serialization;
@@ -110,30 +111,54 @@ private static YamlSequenceNode ToYamlSequence(this JsonArray arr)
             return new YamlSequenceNode(arr.Select(x => x!.ToYamlNode()));
         }
 
+        private static readonly HashSet<string> YamlNullRepresentations = new(StringComparer.Ordinal)
+        {
+            "~",
+            "null",
+            "Null",
+            "NULL"
+        };
+
         private static JsonValue ToJsonValue(this YamlScalarNode yaml)
         {
-            switch (yaml.Style)
+            return yaml.Style switch
             {
-                case ScalarStyle.Plain:
-                    return decimal.TryParse(yaml.Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var d)
-                        ? JsonValue.Create(d)
-                        : bool.TryParse(yaml.Value, out var b)
-                            ? JsonValue.Create(b)
-                            : JsonValue.Create(yaml.Value)!;
-                case ScalarStyle.SingleQuoted:
-                case ScalarStyle.DoubleQuoted:
-                case ScalarStyle.Literal:
-                case ScalarStyle.Folded:
-                case ScalarStyle.Any:
-                    return JsonValue.Create(yaml.Value)!;
-                default:
-                    throw new ArgumentOutOfRangeException();
-            }
+                ScalarStyle.Plain when decimal.TryParse(yaml.Value, NumberStyles.Float, CultureInfo.InvariantCulture, out var d) => JsonValue.Create(d),
+                ScalarStyle.Plain when bool.TryParse(yaml.Value, out var b) => JsonValue.Create(b),
+                ScalarStyle.Plain when YamlNullRepresentations.Contains(yaml.Value) => (JsonValue)JsonNullSentinel.JsonNull.DeepClone(),
+                ScalarStyle.Plain => JsonValue.Create(yaml.Value),
+                ScalarStyle.SingleQuoted or ScalarStyle.DoubleQuoted or ScalarStyle.Literal or ScalarStyle.Folded or ScalarStyle.Any => JsonValue.Create(yaml.Value),
+                _ => throw new ArgumentOutOfRangeException(nameof(yaml)),
+            };
         }
 
         private static YamlScalarNode ToYamlScalar(this JsonValue val)
         {
-            return new YamlScalarNode(val.ToJsonString());
+            // Try to get the underlying value based on its actual type
+            // First try to get it as a string
+            if (val.GetValueKind() == JsonValueKind.String &&
+                val.TryGetValue(out string? stringValue))
+            {
+                // For string values, we need to determine if they should be quoted in YAML
+                // Strings that look like numbers, booleans, or null need to be quoted
+                // to preserve their string type when round-tripping
+                var needsQuoting = decimal.TryParse(stringValue, NumberStyles.Float, CultureInfo.InvariantCulture, out _) ||
+                                   bool.TryParse(stringValue, out _) ||
+                                   YamlNullRepresentations.Contains(stringValue);
+                
+                return new YamlScalarNode(stringValue)
+                {
+                    Style = needsQuoting ? ScalarStyle.DoubleQuoted : ScalarStyle.Plain
+                };
+            }
+            
+            // For non-string values (numbers, booleans, null), use their string representation
+            // These should remain unquoted in YAML
+            var valueString = val.ToString();
+            return new YamlScalarNode(valueString)
+            {
+                Style = ScalarStyle.Plain
+            };
         }
     }
 }

src/Microsoft.OpenApi/JsonNullSentinel.cs

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT license.
+
+using System;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace Microsoft.OpenApi;
+
+/// <summary>
+/// A sentinel value representing JSON null. 
+/// This can only be used for OpenAPI properties of type <see cref="JsonNode"/>
+/// </summary>
+public static class JsonNullSentinel
+{
+    private const string SentinelValue = "openapi-json-null-sentinel-value-2BF93600-0FE4-4250-987A-E5DDB203E464";
+    private static readonly JsonValue SentinelJsonValue = JsonValue.Create(SentinelValue)!;
+    /// <summary>
+	/// A sentinel value representing JSON null. 
+    /// This can only be used for OpenAPI properties of type <see cref="JsonNode"/>.
+    /// This can only be used for the root level of a JSON structure.
+    /// Any use outside of these constraints is unsupported and may lead to unexpected behavior.
+    /// Because the value might be cloned, so the value can be added in a tree, reference equality checks will not work.
+    /// You must use the <see cref="IsJsonNullSentinel(JsonNode?)"/> method to check for this sentinel.
+	/// </summary>
+    public static JsonValue JsonNull => SentinelJsonValue;
+
+    /// <summary>
+    /// Determines if the given node is the JSON null sentinel.
+    /// </summary>
+    /// <param name="node">The JsonNode to check.</param>
+    /// <returns>Whether or not the given node is the JSON null sentinel.</returns>
+    public static bool IsJsonNullSentinel(this JsonNode? node)
+    {
+        return node == SentinelJsonValue ||
+                node is not null &&
+                node.GetValueKind() == JsonValueKind.String &&
+                // using deep equals here results in fewer allocations than TryGetValue
+                JsonNode.DeepEquals(SentinelJsonValue, node);
+    }
+}

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

@@ -12,6 +12,8 @@ public interface IOpenApiExample : IOpenApiDescribedElement, IOpenApiSummarizedE
     /// Embedded literal example. The value field and externalValue field are mutually
     /// exclusive. To represent examples of media types that cannot naturally represented
     /// in JSON or YAML, use a string value to contain the example, escaping where necessary.
+    /// You must use the <see cref="JsonNullSentinel.IsJsonNullSentinel(JsonNode?)"/> method to check whether Default was assigned a null value in the document.
+    /// Assign <see cref="JsonNullSentinel.JsonNull"/> to use get null as a serialized value.
     /// </summary>
     public JsonNode? Value { get; }