Emit nullable/x-nullable property at original location, simplify writing schema type

Author: bkoelman

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -104,6 +104,14 @@ public string? ExclusiveMinimum
         /// <inheritdoc />
         public JsonSchemaType? Type { get; set; }
 
+        // x-nullable is filtered out by deserializers, but keep the check here in case it gets added from user code.
+        private bool IsNullable =>
+            (Type.HasValue && Type.Value.HasFlag(JsonSchemaType.Null)) ||
+            Extensions is not null &&
+            Extensions.TryGetValue(OpenApiConstants.NullableExtension, out var nullExtRawValue) &&
+            nullExtRawValue is JsonNodeExtension { Node: JsonNode jsonNode } &&
+            jsonNode.GetValueKind() is JsonValueKind.True;
+
         /// <inheritdoc />
         public string? Const { get; set; }
 
@@ -437,7 +445,7 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             writer.WriteOptionalCollection(OpenApiConstants.Enum, Enum, (nodeWriter, s) => nodeWriter.WriteAny(s));
 
             // type
-            SerializeTypeProperty(Type, writer, version);
+            SerializeTypeProperty(writer, version);
 
             // allOf
             writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, callback);
@@ -479,6 +487,12 @@ private void SerializeInternal(IOpenApiWriter writer, OpenApiSpecVersion version
             // default
             writer.WriteOptionalObject(OpenApiConstants.Default, Default, (w, d) => w.WriteAny(d));
 
+            // nullable
+            if (version == OpenApiSpecVersion.OpenApi3_0)
+            {
+                SerializeNullable(writer, version);
+            }
+
             // discriminator
             writer.WriteOptionalObject(OpenApiConstants.Discriminator, Discriminator, callback);
 
@@ -619,7 +633,7 @@ private void SerializeAsV2(
             writer.WriteStartObject();
 
             // type
-            SerializeTypeProperty(Type, writer, OpenApiSpecVersion.OpenApi2_0);
+            SerializeTypeProperty(writer, OpenApiSpecVersion.OpenApi2_0);
 
             // description
             writer.WriteProperty(OpenApiConstants.Description, Description);
@@ -742,66 +756,36 @@ private void SerializeAsV2(
             // example
             writer.WriteOptionalObject(OpenApiConstants.Example, Example, (w, e) => w.WriteAny(e));
 
+            // x-nullable extension
+            SerializeNullable(writer, OpenApiSpecVersion.OpenApi2_0);
+
             // extensions
             writer.WriteExtensions(Extensions, OpenApiSpecVersion.OpenApi2_0);
 
             writer.WriteEndObject();
         }
 
-        private void SerializeTypeProperty(JsonSchemaType? type, IOpenApiWriter writer, OpenApiSpecVersion version)
+        private void SerializeTypeProperty(IOpenApiWriter writer, OpenApiSpecVersion version)
         {
-            // check whether nullable is true for upcasting purposes
-            var isNullable = (Type.HasValue && Type.Value.HasFlag(JsonSchemaType.Null)) ||
-                                Extensions is not null &&
-                                Extensions.TryGetValue(OpenApiConstants.NullableExtension, out var nullExtRawValue) &&
-                                nullExtRawValue is JsonNodeExtension { Node: JsonNode jsonNode } &&
-                                jsonNode.GetValueKind() is JsonValueKind.True;
-            if (type is null)
+            if (Type is null)
             {
-                if (version is OpenApiSpecVersion.OpenApi3_0 && isNullable)
-                {
-                    writer.WriteProperty(OpenApiConstants.Nullable, true);
-                }
+                return;
             }
-            else if (!HasMultipleTypes(type.Value))
-            {
-                switch (version)
-                {
-                    case OpenApiSpecVersion.OpenApi3_1 when isNullable:
-                        UpCastSchemaTypeToV31(type.Value, writer);
-                        break;
-                    case OpenApiSpecVersion.OpenApi3_0 when isNullable && type.Value == JsonSchemaType.Null:
-                        writer.WriteProperty(OpenApiConstants.Nullable, true);
-                        break;
-                    case OpenApiSpecVersion.OpenApi3_0 when isNullable && type.Value != JsonSchemaType.Null:
-                        writer.WriteProperty(OpenApiConstants.Nullable, true);
-                        writer.WriteProperty(OpenApiConstants.Type, type.Value.ToFirstIdentifier());
-                        break;
-                    default:
-                        writer.WriteProperty(OpenApiConstants.Type, type.Value.ToFirstIdentifier());
-                        break;
-                }
-            }
-            else
+
+            var unifiedType = IsNullable ? Type.Value | JsonSchemaType.Null : Type.Value;
+            var typeWithoutNull = unifiedType & ~JsonSchemaType.Null;
+
+            switch (version)
             {
-                // type
-                if (version is OpenApiSpecVersion.OpenApi2_0 || version is OpenApiSpecVersion.OpenApi3_0)
-                {
-                    DowncastTypeArrayToV2OrV3(type.Value, writer, version);
-                }
-                else
-                {
-                    var list = (from JsonSchemaType flag in jsonSchemaTypeValues
-                                where type.Value.HasFlag(flag)
-                                select flag).ToList();
-                    writer.WriteOptionalCollection(OpenApiConstants.Type, list, (w, s) =>
+                case OpenApiSpecVersion.OpenApi2_0 or OpenApiSpecVersion.OpenApi3_0:
+                    if (typeWithoutNull != 0 && !HasMultipleTypes(typeWithoutNull))
                     {
-                        foreach (var item in s.ToIdentifiers())
-                        {
-                            w.WriteValue(item);
-                        }
-                    });
-                }
+                        writer.WriteProperty(OpenApiConstants.Type, typeWithoutNull.ToFirstIdentifier());
+                    }
+                    break;
+                default:
+                    WriteUnifiedSchemaType(unifiedType, writer);
+                    break;
             }
         }
 
@@ -813,20 +797,17 @@ private static bool IsPowerOfTwo(int x)
         private static bool HasMultipleTypes(JsonSchemaType schemaType)
         {
             var schemaTypeNumeric = (int)schemaType;
-            return !IsPowerOfTwo(schemaTypeNumeric) && // Boolean, Integer, Number, String, Array, Object
-                    schemaTypeNumeric != (int)JsonSchemaType.Null;
+            return !IsPowerOfTwo(schemaTypeNumeric);
         }
 
-        private static void UpCastSchemaTypeToV31(JsonSchemaType type, IOpenApiWriter writer)
+        private static void WriteUnifiedSchemaType(JsonSchemaType type, IOpenApiWriter writer)
         {
-            // create a new array and insert the type and "null" as values
-            var temporaryType = type | JsonSchemaType.Null;
-            var list = (from JsonSchemaType flag in jsonSchemaTypeValues// Check if the flag is set in 'type' using a bitwise AND operation
-                        where temporaryType.HasFlag(flag)
-                        select flag.ToFirstIdentifier()).ToList();
-            if (list.Count > 1)
+            var array = (from JsonSchemaType flag in jsonSchemaTypeValues
+                        where type.HasFlag(flag)
+                        select flag.ToFirstIdentifier()).ToArray();
+            if (array.Length > 1)
             {
-                writer.WriteOptionalCollection(OpenApiConstants.Type, list, (w, s) =>
+                writer.WriteOptionalCollection(OpenApiConstants.Type, array, (w, s) =>
                 {
                     if (!string.IsNullOrEmpty(s) && s is not null)
                     {
@@ -836,54 +817,32 @@ where temporaryType.HasFlag(flag)
             }
             else
             {
-                writer.WriteProperty(OpenApiConstants.Type, list[0]);
+                writer.WriteProperty(OpenApiConstants.Type, array[0]);
             }
         }
 
-#if NET5_0_OR_GREATER
-        private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues<JsonSchemaType>();
-#else
-        private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues(typeof(JsonSchemaType));
-#endif
-
-        private static void DowncastTypeArrayToV2OrV3(JsonSchemaType schemaType, IOpenApiWriter writer, OpenApiSpecVersion version)
+        private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version)
         {
-            /* If the array has one non-null value, emit Type as string
-            * If the array has one null value, emit x-nullable as true
-            * If the array has two values, one null and one non-null, emit Type as string and x-nullable as true
-            * If the array has more than two values or two non-null values, do not emit type
-            * */
-
-            var nullableProp = version.Equals(OpenApiSpecVersion.OpenApi2_0)
-                ? OpenApiConstants.NullableExtension
-                : OpenApiConstants.Nullable;
-
-            if (!HasMultipleTypes(schemaType & ~JsonSchemaType.Null) && (schemaType & JsonSchemaType.Null) == JsonSchemaType.Null) // checks for two values and one is null
-            {
-                foreach (JsonSchemaType flag in jsonSchemaTypeValues)
-                {
-                    // Skip if the flag is not set or if it's the Null flag
-                    if (schemaType.HasFlag(flag) && flag != JsonSchemaType.Null)
-                    {
-                        // Write the non-null flag value to the writer
-                        writer.WriteProperty(OpenApiConstants.Type, flag.ToFirstIdentifier());
-                    }
-                }
-                writer.WriteProperty(nullableProp, true);
-            }
-            else if (!HasMultipleTypes(schemaType))
+            if (IsNullable)
             {
-                if (schemaType is JsonSchemaType.Null)
-                {
-                    writer.WriteProperty(nullableProp, true);
-                }
-                else
+                switch (version)
                 {
-                    writer.WriteProperty(OpenApiConstants.Type, schemaType.ToFirstIdentifier());
+                    case OpenApiSpecVersion.OpenApi2_0:
+                        writer.WriteProperty(OpenApiConstants.NullableExtension, true);
+                        break;
+                    case OpenApiSpecVersion.OpenApi3_0:
+                        writer.WriteProperty(OpenApiConstants.Nullable, true);
+                        break;
                 }
             }
         }
 
+#if NET5_0_OR_GREATER
+        private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues<JsonSchemaType>();
+#else
+        private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues(typeof(JsonSchemaType));
+#endif
+
         /// <inheritdoc/>
         public IOpenApiSchema CreateShallowCopy()
         {

src/Microsoft.OpenApi/Reader/V2/OpenApiSchemaDeserializer.cs

@@ -271,6 +271,16 @@ public static IOpenApiSchema LoadSchema(ParseNode node, OpenApiDocument hostDocu
                 propertyNode.ParseField(schema, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument);
             }
 
+            if (schema.Extensions is not null && schema.Extensions.ContainsKey(OpenApiConstants.NullableExtension))
+            {
+                if (schema.Type.HasValue)
+                    schema.Type |= JsonSchemaType.Null;
+                else
+                    schema.Type = JsonSchemaType.Null;
+
+                schema.Extensions.Remove(OpenApiConstants.NullableExtension);
+            }
+
             return schema;
         }
     }

src/Microsoft.OpenApi/Reader/V3/OpenApiSchemaDeserializer.cs

@@ -307,6 +307,16 @@ public static IOpenApiSchema LoadSchema(ParseNode node, OpenApiDocument hostDocu
                 propertyNode.ParseField(schema, _openApiSchemaFixedFields, _openApiSchemaPatternFields, hostDocument);
             }
 
+            if (schema.Extensions is not null && schema.Extensions.ContainsKey(OpenApiConstants.NullableExtension))
+            {
+                if (schema.Type.HasValue)
+                    schema.Type |= JsonSchemaType.Null;
+                else
+                    schema.Type = JsonSchemaType.Null;
+
+                schema.Extensions.Remove(OpenApiConstants.NullableExtension);
+            }
+
             return schema;
         }
     }

test/Microsoft.OpenApi.Readers.Tests/V31Tests/OpenApiSchemaTests.cs

@@ -384,8 +384,7 @@ public async Task SerializeV2SchemaWithNullableExtensionAsV31Works()
             // Arrange
             var expected = @"type:
   - 'null'
-  - string
-x-nullable: true";
+  - string";
 
             var path = Path.Combine(SampleFolderPath, "schemaWithNullableExtension.yaml");
 
@@ -407,7 +406,7 @@ public void SerializeSchemaWithTypeArrayAndNullableDoesntEmitType()
 - ""int""
 nullable: true";
 
-            var expected = @"{ }";
+            var expected = @"x-nullable: true";
 
             var schema = OpenApiModelFactory.Parse<OpenApiSchema>(input, OpenApiSpecVersion.OpenApi3_1, new(), out _, "yaml", SettingsFixture.ReaderSettings);
 

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.SerializeReferencedSchemaAsV3JsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -5,8 +5,8 @@
   "minimum": 10,
   "exclusiveMinimum": true,
   "type": "integer",
-  "nullable": true,
   "default": 15,
+  "nullable": true,
   "externalDocs": {
     "url": "http://example.com/externalDocs"
   }

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.SerializeReferencedSchemaAsV3JsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -1 +1 @@
-{"title":"title1","multipleOf":3,"maximum":42,"minimum":10,"exclusiveMinimum":true,"type":"integer","nullable":true,"default":15,"externalDocs":{"url":"http://example.com/externalDocs"}}
+{"title":"title1","multipleOf":3,"maximum":42,"minimum":10,"exclusiveMinimum":true,"type":"integer","default":15,"nullable":true,"externalDocs":{"url":"http://example.com/externalDocs"}}

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.SerializeReferencedSchemaAsV3WithoutReferenceJsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -5,8 +5,8 @@
   "minimum": 10,
   "exclusiveMinimum": true,
   "type": "integer",
-  "nullable": true,
   "default": 15,
+  "nullable": true,
   "externalDocs": {
     "url": "http://example.com/externalDocs"
   }

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.SerializeReferencedSchemaAsV3WithoutReferenceJsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -1 +1 @@
-{"title":"title1","multipleOf":3,"maximum":42,"minimum":10,"exclusiveMinimum":true,"type":"integer","nullable":true,"default":15,"externalDocs":{"url":"http://example.com/externalDocs"}}
+{"title":"title1","multipleOf":3,"maximum":42,"minimum":10,"exclusiveMinimum":true,"type":"integer","default":15,"nullable":true,"externalDocs":{"url":"http://example.com/externalDocs"}}

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.SerializeSchemaWRequiredPropertiesAsV2JsonWorksAsync_produceTerseOutput=False.verified.txt

@@ -1,6 +1,5 @@
 {
   "type": "object",
-  "x-nullable": true,
   "title": "title1",
   "required": [
     "property1"
@@ -39,5 +38,6 @@
   },
   "externalDocs": {
     "url": "http://example.com/externalDocs"
-  }
+  },
+  "x-nullable": true
 }

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.SerializeSchemaWRequiredPropertiesAsV2JsonWorksAsync_produceTerseOutput=True.verified.txt

@@ -1 +1 @@
-{"type":"object","x-nullable":true,"title":"title1","required":["property1"],"properties":{"property1":{"required":["property3"],"properties":{"property2":{"type":"integer"},"property3":{"type":"string","maxLength":15}}},"property4":{"properties":{"property5":{"properties":{"property6":{"type":"boolean"}}},"property7":{"type":"string","minLength":2}},"readOnly":true}},"externalDocs":{"url":"http://example.com/externalDocs"}}
+{"type":"object","title":"title1","required":["property1"],"properties":{"property1":{"required":["property3"],"properties":{"property2":{"type":"integer"},"property3":{"type":"string","maxLength":15}}},"property4":{"properties":{"property5":{"properties":{"property6":{"type":"boolean"}}},"property7":{"type":"string","minLength":2}},"readOnly":true}},"externalDocs":{"url":"http://example.com/externalDocs"},"x-nullable":true}