[release/10.0-rc1] Model nullable types using oneOf in OpenAPI schema

src/OpenApi/sample/Endpoints/MapSchemasEndpoints.cs

@@ -46,6 +46,32 @@ public static IEndpointRouteBuilder MapSchemasEndpoints(this IEndpointRouteBuild
         schemas.MapPost("/config-with-generic-lists", (Config config) => Results.Ok(config));
         schemas.MapPost("/project-response", (ProjectResponse project) => Results.Ok(project));
         schemas.MapPost("/subscription", (Subscription subscription) => Results.Ok(subscription));
+
+        // Tests for oneOf nullable behavior on responses and request bodies
+        schemas.MapGet("/nullable-response", () => TypedResults.Ok(new NullableResponseModel
+        {
+            RequiredProperty = "required",
+            NullableProperty = null,
+            NullableComplexProperty = null
+        }));
+        schemas.MapGet("/nullable-return-type", NullableResponseModel? () => new NullableResponseModel
+        {
+            RequiredProperty = "required",
+            NullableProperty = null,
+            NullableComplexProperty = null
+        });
+        schemas.MapPost("/nullable-request", (NullableRequestModel? request) => Results.Ok(request));
+        schemas.MapPost("/complex-nullable-hierarchy", (ComplexHierarchyModel model) => Results.Ok(model));
+
+        // Additional edge cases for nullable testing
+        schemas.MapPost("/nullable-array-elements", (NullableArrayModel model) => Results.Ok(model));
+        schemas.MapGet("/optional-with-default", () => TypedResults.Ok(new ModelWithDefaults()));
+        schemas.MapGet("/nullable-enum-response", () => TypedResults.Ok(new EnumNullableModel
+        {
+            RequiredEnum = TestEnum.Value1,
+            NullableEnum = null
+        }));
+
         return endpointRouteBuilder;
     }
 
@@ -173,4 +199,73 @@ public sealed class RefUser
         public string Name { get; set; } = "";
         public string Email { get; set; } = "";
     }
+
+    // Models for testing oneOf nullable behavior
+    public sealed class NullableResponseModel
+    {
+        public required string RequiredProperty { get; set; }
+        public string? NullableProperty { get; set; }
+        public ComplexType? NullableComplexProperty { get; set; }
+    }
+
+    public sealed class NullableRequestModel
+    {
+        public required string RequiredField { get; set; }
+        public string? OptionalField { get; set; }
+        public List<string>? NullableList { get; set; }
+        public Dictionary<string, string?>? NullableDictionary { get; set; }
+    }
+
+    // Complex hierarchy model for testing nested nullable properties
+    public sealed class ComplexHierarchyModel
+    {
+        public required string Id { get; set; }
+        public NestedModel? OptionalNested { get; set; }
+        public required NestedModel RequiredNested { get; set; }
+        public List<NestedModel?>? NullableListWithNullableItems { get; set; }
+    }
+
+    public sealed class NestedModel
+    {
+        public required string Name { get; set; }
+        public int? OptionalValue { get; set; }
+        public ComplexType? DeepNested { get; set; }
+    }
+
+    public sealed class ComplexType
+    {
+        public string? Description { get; set; }
+        public DateTime? Timestamp { get; set; }
+    }
+
+    // Additional models for edge case testing
+    public sealed class NullableArrayModel
+    {
+        public string[]? NullableArray { get; set; }
+        public List<string?> ListWithNullableElements { get; set; } = [];
+        public Dictionary<string, string?>? NullableDictionaryWithNullableValues { get; set; }
+    }
+
+    public sealed class ModelWithDefaults
+    {
+        public string PropertyWithDefault { get; set; } = "default";
+        public string? NullableWithNull { get; set; }
+        public int NumberWithDefault { get; set; } = 42;
+        public bool BoolWithDefault { get; set; } = true;
+    }
+
+    // Enum testing with nullable
+    public enum TestEnum
+    {
+        Value1,
+        Value2,
+        Value3
+    }
+
+    public sealed class EnumNullableModel
+    {
+        public required TestEnum RequiredEnum { get; set; }
+        public TestEnum? NullableEnum { get; set; }
+        public List<TestEnum?> ListOfNullableEnums { get; set; } = [];
+    }
 }

src/OpenApi/src/Extensions/JsonNodeSchemaExtensions.cs

@@ -195,11 +195,6 @@ internal static void ApplyDefaultValue(this JsonNode schema, object? defaultValu
     /// underlying schema generator does not support this, we need to manually apply the
     /// supported formats to the schemas associated with the generated type.
     ///
-    /// Whereas JsonSchema represents nullable types via `type: ["string", "null"]`, OpenAPI
-    /// v3 exposes a nullable property on the schema. This method will set the nullable property
-    /// based on whether the underlying schema generator returned an array type containing "null" to
-    /// represent a nullable type or if the type was denoted as nullable from our lookup cache.
-    ///
     /// Note that this method targets <see cref="JsonNode"/> and not <see cref="OpenApiSchema"/> because
     /// it is is designed to be invoked via the `OnGenerated` callback in the underlying schema generator as
     /// opposed to after the generated schemas have been mapped to OpenAPI schemas.
@@ -349,8 +344,6 @@ internal static void ApplyParameterInfo(this JsonNode schema, ApiParameterDescri
             {
                 schema.ApplyValidationAttributes(validationAttributes);
             }
-
-            schema.ApplyNullabilityContextInfo(parameterInfo);
         }
         // Route constraints are only defined on parameters that are sourced from the path. Since
         // they are encoded in the route template, and not in the type information based to the underlying
@@ -451,42 +444,49 @@ private static bool IsNonAbstractTypeWithoutDerivedTypeReference(JsonSchemaExpor
     }
 
     /// <summary>
-    /// Support applying nullability status for reference types provided as a parameter.
+    /// Support applying nullability status for reference types provided as a property or field.
     /// </summary>
     /// <param name="schema">The <see cref="JsonNode"/> produced by the underlying schema generator.</param>
-    /// <param name="parameterInfo">The <see cref="ParameterInfo" /> associated with the schema.</param>
-    internal static void ApplyNullabilityContextInfo(this JsonNode schema, ParameterInfo parameterInfo)
+    /// <param name="propertyInfo">The <see cref="JsonPropertyInfo" /> associated with the schema.</param>
+    internal static void ApplyNullabilityContextInfo(this JsonNode schema, JsonPropertyInfo propertyInfo)
     {
-        if (parameterInfo.ParameterType.IsValueType)
+        // Avoid setting explicit nullability annotations for `object` types so they continue to match on the catch
+        // all schema (no type, no format, no constraints).
+        if (propertyInfo.PropertyType != typeof(object) && (propertyInfo.IsGetNullable || propertyInfo.IsSetNullable))
         {
-            return;
+            if (MapJsonNodeToSchemaType(schema[OpenApiSchemaKeywords.TypeKeyword]) is { } schemaTypes &&
+                !schemaTypes.HasFlag(JsonSchemaType.Null))
+            {
+                schema[OpenApiSchemaKeywords.TypeKeyword] = (schemaTypes | JsonSchemaType.Null).ToString();
+            }
         }
-
-        var nullabilityInfoContext = new NullabilityInfoContext();
-        var nullabilityInfo = nullabilityInfoContext.Create(parameterInfo);
-        if (nullabilityInfo.WriteState == NullabilityState.Nullable
-            && MapJsonNodeToSchemaType(schema[OpenApiSchemaKeywords.TypeKeyword]) is { } schemaTypes
-            && !schemaTypes.HasFlag(JsonSchemaType.Null))
+        if (schema[OpenApiConstants.SchemaId] is not null &&
+            propertyInfo.PropertyType != typeof(object) && propertyInfo.ShouldApplyNullablePropertySchema())
         {
-            schema[OpenApiSchemaKeywords.TypeKeyword] = (schemaTypes | JsonSchemaType.Null).ToString();
+            schema[OpenApiConstants.NullableProperty] = true;
         }
     }
 
     /// <summary>
-    /// Support applying nullability status for reference types provided as a property or field.
+    /// Prunes the "null" type from the schema for types that are componentized. These
+    /// types should represent their nullability using oneOf with null instead.
     /// </summary>
     /// <param name="schema">The <see cref="JsonNode"/> produced by the underlying schema generator.</param>
-    /// <param name="propertyInfo">The <see cref="JsonPropertyInfo" /> associated with the schema.</param>
-    internal static void ApplyNullabilityContextInfo(this JsonNode schema, JsonPropertyInfo propertyInfo)
+    internal static void PruneNullTypeForComponentizedTypes(this JsonNode schema)
     {
-        // Avoid setting explicit nullability annotations for `object` types so they continue to match on the catch
-        // all schema (no type, no format, no constraints).
-        if (propertyInfo.PropertyType != typeof(object) && (propertyInfo.IsGetNullable || propertyInfo.IsSetNullable))
+        if (schema[OpenApiConstants.SchemaId] is not null &&
+                schema[OpenApiSchemaKeywords.TypeKeyword] is JsonArray typeArray)
         {
-            if (MapJsonNodeToSchemaType(schema[OpenApiSchemaKeywords.TypeKeyword]) is { } schemaTypes &&
-                !schemaTypes.HasFlag(JsonSchemaType.Null))
+            for (var i = typeArray.Count - 1; i >= 0; i--)
             {
-                schema[OpenApiSchemaKeywords.TypeKeyword] = (schemaTypes | JsonSchemaType.Null).ToString();
+                if (typeArray[i]?.GetValue<string>() == "null")
+                {
+                    typeArray.RemoveAt(i);
+                }
+            }
+            if (typeArray.Count == 1)
+            {
+                schema[OpenApiSchemaKeywords.TypeKeyword] = typeArray[0]?.GetValue<string>();
             }
         }
     }

src/OpenApi/src/Extensions/JsonTypeInfoExtensions.cs

@@ -108,6 +108,12 @@ internal static string GetSchemaReferenceId(this Type type, JsonSerializerOption
             return $"{typeName}Of{propertyNames}";
         }
 
+        // Special handling for nullable value types
+        if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>))
+        {
+            return type.GetGenericArguments()[0].GetSchemaReferenceId(options);
+        }
+
         // Special handling for generic types that are collections
         // Generic types become a concatenation of the generic type name and the type arguments
         if (type.IsGenericType)

src/OpenApi/src/Extensions/OpenApiSchemaExtensions.cs

@@ -0,0 +1,21 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+namespace Microsoft.AspNetCore.OpenApi;
+
+internal static class OpenApiSchemaExtensions
+{
+    private static readonly OpenApiSchema _nullSchema = new() { Type = JsonSchemaType.Null };
+
+    public static IOpenApiSchema CreateOneOfNullableWrapper(this IOpenApiSchema originalSchema)
+    {
+        return new OpenApiSchema
+        {
+            OneOf =
+            [
+                _nullSchema,
+                originalSchema
+            ]
+        };
+    }
+}

src/OpenApi/src/Extensions/TypeExtensions.cs

@@ -1,6 +1,13 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Linq;
+using System.Reflection;
+using System.Text.Json.Serialization.Metadata;
+using Microsoft.AspNetCore.Mvc.ApiExplorer;
+using Microsoft.AspNetCore.Mvc.Controllers;
+using Microsoft.AspNetCore.Mvc.Infrastructure;
+
 namespace Microsoft.AspNetCore.OpenApi;
 
 internal static class TypeExtensions
@@ -30,4 +37,73 @@ public static bool IsJsonPatchDocument(this Type type)
 
         return false;
     }
+
+    public static bool ShouldApplyNullableResponseSchema(this ApiResponseType apiResponseType, ApiDescription apiDescription)
+    {
+        // Get the MethodInfo from the ActionDescriptor
+        var responseType = apiResponseType.Type;
+        var methodInfo = apiDescription.ActionDescriptor is ControllerActionDescriptor controllerActionDescriptor
+            ? controllerActionDescriptor.MethodInfo
+            : apiDescription.ActionDescriptor.EndpointMetadata.OfType<MethodInfo>().SingleOrDefault();
+
+        if (methodInfo is null)
+        {
+            return false;
+        }
+
+        var returnType = methodInfo.ReturnType;
+        if (returnType.IsGenericType &&
+            (returnType.GetGenericTypeDefinition() == typeof(Task<>) || returnType.GetGenericTypeDefinition() == typeof(ValueTask<>)))
+        {
+            returnType = returnType.GetGenericArguments()[0];
+        }
+        if (returnType != responseType)
+        {
+            return false;
+        }
+
+        if (returnType.IsValueType)
+        {
+            return apiResponseType.ModelMetadata?.IsNullableValueType ?? false;
+        }
+
+        var nullabilityInfoContext = new NullabilityInfoContext();
+        var nullabilityInfo = nullabilityInfoContext.Create(methodInfo.ReturnParameter);
+        return nullabilityInfo.WriteState == NullabilityState.Nullable;
+    }
+
+    public static bool ShouldApplyNullableRequestSchema(this ApiParameterDescription apiParameterDescription)
+    {
+        var parameterType = apiParameterDescription.Type;
+        if (parameterType is null)
+        {
+            return false;
+        }
+
+        if (apiParameterDescription.ParameterDescriptor is not IParameterInfoParameterDescriptor { ParameterInfo: { } parameterInfo })
+        {
+            return false;
+        }
+
+        if (parameterType.IsValueType)
+        {
+            return apiParameterDescription.ModelMetadata?.IsNullableValueType ?? false;
+        }
+
+        var nullabilityInfoContext = new NullabilityInfoContext();
+        var nullabilityInfo = nullabilityInfoContext.Create(parameterInfo);
+        return nullabilityInfo.WriteState == NullabilityState.Nullable;
+    }
+
+    public static bool ShouldApplyNullablePropertySchema(this JsonPropertyInfo jsonPropertyInfo)
+    {
+        if (jsonPropertyInfo.AttributeProvider is not PropertyInfo propertyInfo)
+        {
+            return false;
+        }
+
+        var nullabilityInfoContext = new NullabilityInfoContext();
+        var nullabilityInfo = nullabilityInfoContext.Create(propertyInfo);
+        return nullabilityInfo.WriteState == NullabilityState.Nullable;
+    }
 }

src/OpenApi/src/Schemas/OpenApiJsonSchema.Helpers.cs

@@ -333,6 +333,11 @@ public static void ReadProperty(ref Utf8JsonReader reader, string propertyName,
                 schema.Metadata ??= new Dictionary<string, object>();
                 schema.Metadata.Add(OpenApiConstants.SchemaId, reader.GetString() ?? string.Empty);
                 break;
+            case OpenApiConstants.NullableProperty:
+                reader.Read();
+                schema.Metadata ??= new Dictionary<string, object>();
+                schema.Metadata.Add(OpenApiConstants.NullableProperty, reader.GetBoolean());
+                break;
             // OpenAPI does not support the `const` keyword in its schema implementation, so
             // we map it to its closest approximation, an enum with a single value, here.
             case OpenApiSchemaKeywords.ConstKeyword:

src/OpenApi/src/Services/OpenApiConstants.cs

@@ -17,6 +17,7 @@ internal static class OpenApiConstants
     internal const string RefExampleAnnotation = "x-ref-example";
     internal const string RefKeyword = "$ref";
     internal const string RefPrefix = "#";
+    internal const string NullableProperty = "x-is-nullable-property";
     internal const string DefaultOpenApiResponseKey = "default";
     // Since there's a finite set of HTTP methods that can be included in a given
     // OpenApiPaths, we can pre-allocate an array of these methods and use a direct

src/OpenApi/src/Services/OpenApiDocumentService.cs

@@ -423,8 +423,15 @@ private async Task<OpenApiResponse> GetResponseAsync(
             .Select(responseFormat => responseFormat.MediaType);
         foreach (var contentType in apiResponseFormatContentTypes)
         {
-            var schema = apiResponseType.Type is { } type ? await _componentService.GetOrCreateSchemaAsync(document, type, scopedServiceProvider, schemaTransformers, null, cancellationToken) : new OpenApiSchema();
-            response.Content[contentType] = new OpenApiMediaType { Schema = schema };
+            IOpenApiSchema? schema = null;
+            if (apiResponseType.Type is { } responseType)
+            {
+                schema = await _componentService.GetOrCreateSchemaAsync(document, responseType, scopedServiceProvider, schemaTransformers, null, cancellationToken);
+                schema = apiResponseType.ShouldApplyNullableResponseSchema(apiDescription)
+                    ? schema.CreateOneOfNullableWrapper()
+                    : schema;
+            }
+            response.Content[contentType] = new OpenApiMediaType { Schema = schema ?? new OpenApiSchema() };
         }
 
         // MVC's `ProducesAttribute` doesn't implement the produces metadata that the ApiExplorer
@@ -744,7 +751,11 @@ private async Task<OpenApiRequestBody> GetJsonRequestBody(
         foreach (var requestFormat in supportedRequestFormats)
         {
             var contentType = requestFormat.MediaType;
-            requestBody.Content[contentType] = new OpenApiMediaType { Schema = await _componentService.GetOrCreateSchemaAsync(document, bodyParameter.Type, scopedServiceProvider, schemaTransformers, bodyParameter, cancellationToken: cancellationToken) };
+            var schema = await _componentService.GetOrCreateSchemaAsync(document, bodyParameter.Type, scopedServiceProvider, schemaTransformers, bodyParameter, cancellationToken: cancellationToken);
+            schema = bodyParameter.ShouldApplyNullableRequestSchema()
+                ? schema.CreateOneOfNullableWrapper()
+                : schema;
+            requestBody.Content[contentType] = new OpenApiMediaType { Schema = schema };
         }
 
         return requestBody;