fix: adds a null value sentinel to enable roundtrip serializations of JsonNode typed properties

Signed-off-by: Vincent Biret <[email protected]>

Author: baywet

src/Microsoft.OpenApi.YamlReader/YamlConverter.cs

@@ -18,7 +18,7 @@ public static class YamlConverter
         /// </summary>
         /// <param name="yaml">The YAML stream.</param>
         /// <returns>A collection of nodes representing the YAML documents in the stream.</returns>
-        public static IEnumerable<JsonNode?> ToJsonNode(this YamlStream yaml)
+        public static IEnumerable<JsonNode> ToJsonNode(this YamlStream yaml)
         {
             return yaml.Documents.Select(x => x.ToJsonNode());
         }
@@ -28,7 +28,7 @@ public static class YamlConverter
         /// </summary>
         /// <param name="yaml">The YAML document.</param>
         /// <returns>A `JsonNode` representative of the YAML document.</returns>
-        public static JsonNode? ToJsonNode(this YamlDocument yaml)
+        public static JsonNode ToJsonNode(this YamlDocument yaml)
         {
             return yaml.RootNode.ToJsonNode();
         }
@@ -39,7 +39,7 @@ public static class YamlConverter
         /// <param name="yaml">The YAML node.</param>
         /// <returns>A `JsonNode` representative of the YAML node.</returns>
         /// <exception cref="NotSupportedException">Thrown for YAML that is not compatible with JSON.</exception>
-        public static JsonNode? ToJsonNode(this YamlNode yaml)
+        public static JsonNode ToJsonNode(this YamlNode yaml)
         {
             return yaml switch
             {
@@ -118,13 +118,13 @@ private static YamlSequenceNode ToYamlSequence(this JsonArray arr)
             "NULL"
         };
 
-        private static JsonValue? ToJsonValue(this YamlScalarNode yaml)
+        private static JsonValue ToJsonValue(this YamlScalarNode yaml)
         {
             return yaml.Style switch
             {
                 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) => null,
+                ScalarStyle.Plain when YamlNullRepresentations.Contains(yaml.Value) => JsonNullSentinel.JsonNull,
                 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)),

src/Microsoft.OpenApi/JsonNullSentinel.cs

@@ -0,0 +1,40 @@
+// 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 this is returning a cloned instance, 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 => (JsonValue)SentinelJsonValue.DeepClone();
+
+    /// <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 is JsonValue jsonValue &&
+                jsonValue.GetValueKind() == JsonValueKind.String &&
+                jsonValue.TryGetValue<string>(out var value) &&
+                SentinelValue.Equals(value, StringComparison.Ordinal);
+    }
+}

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; }
 

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

@@ -48,6 +48,8 @@ public interface IOpenApiHeader : IOpenApiDescribedElement, IOpenApiReadOnlyExte
 
     /// <summary>
     /// Example of the media type.
+    /// 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? Example { get; }
 

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

@@ -89,6 +89,8 @@ public interface IOpenApiParameter : IOpenApiDescribedElement, IOpenApiReadOnlyE
     /// the example value SHALL override the example provided by the schema.
     /// To represent examples of media types that cannot naturally be represented in JSON or YAML,
     /// a string value can contain the example with 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? Example { get; }
 

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

@@ -117,6 +117,8 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided.
     /// Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level.
     /// For example, if type is string, then default can be "foo" but cannot be 1.
+    /// 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? Default { get; }
 
@@ -238,6 +240,8 @@ public interface IOpenApiSchema : IOpenApiDescribedElement, IOpenApiReadOnlyExte
     /// A free-form property to include an example of an instance for this schema.
     /// To represent examples that cannot be naturally represented in JSON or YAML,
     /// a string value can be used to contain the example with 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? Example { get; }
 

src/Microsoft.OpenApi/Models/JsonSchemaReference.cs

@@ -17,6 +17,8 @@ public class JsonSchemaReference : OpenApiReferenceWithDescription
     /// <summary>
     /// A default value which by default SHOULD override that of the referenced component.
     /// If the referenced object-type does not allow a default field, then this field has no effect.
+    /// 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? Default { get; set; }
 

src/Microsoft.OpenApi/Models/OpenApiMediaType.cs

@@ -21,6 +21,8 @@ public class OpenApiMediaType : IOpenApiSerializable, IOpenApiExtensible
         /// <summary>
         /// Example of the media type.
         /// The example object SHOULD be in the correct format as specified by the media type.
+        /// 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? Example { get; set; }
 

src/Microsoft.OpenApi/Models/RuntimeExpressionAnyWrapper.cs

@@ -29,6 +29,8 @@ public RuntimeExpressionAnyWrapper(RuntimeExpressionAnyWrapper runtimeExpression
 
         /// <summary>
         /// Gets/Sets the <see cref="JsonNode"/>
+        /// 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? Any
         {

src/Microsoft.OpenApi/Reader/ParseNodes/MapNode.cs

@@ -30,15 +30,19 @@ public MapNode(ParsingContext context, JsonNode node) : base(
 
             _node = mapNode;
             _nodes = _node.Where(p => p.Value is not null).OfType<KeyValuePair<string, JsonNode>>().Select(p => new PropertyNode(Context, p.Key, p.Value)).ToList();
+            _nodes.AddRange(_node.Where(p => p.Value is null).Select(p => new PropertyNode(Context, p.Key, JsonNullSentinel.JsonNull)));
         }
 
         public PropertyNode? this[string key]
         {
             get
             {
-                if (_node.TryGetPropertyValue(key, out var node) && node is not null)
+                if (_node.TryGetPropertyValue(key, out var node))
                 {
-                    return new(Context, key, node);
+                    if (node is not null)
+                        return new(Context, key, node);
+                    else
+                        return new(Context, key, JsonNullSentinel.JsonNull);
                 }
 
                 return null;