feat/null downcasting to v3

CHANGELOG.md

@@ -2,7 +2,6 @@
 
 ## [3.0.3](https://github.com/microsoft/OpenAPI.NET/compare/v3.0.2...v3.0.3) (2025-12-16)
 
-
 ### Bug Fixes
 
 * load JSON documents that are preceded by multiple whitespace ([6461bac](https://github.com/microsoft/OpenAPI.NET/commit/6461bac01c4176424210e9ac249698f665a514a6))
@@ -37,6 +36,16 @@
 
 * adds support for OpenAPI 3.2.0 ([765a8dd](https://github.com/microsoft/OpenAPI.NET/commit/765a8dd4d6efd1a31b6a76d282ccffa5877a845a))
 
+## [2.3.12](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.11...v2.3.12) (2025-12-15)
+
+
+### Bug Fixes
+
+* load JSON documents that are preceded by multiple whitespace ([640e59a](https://github.com/microsoft/OpenAPI.NET/commit/640e59a143a2a6d3b79c9f6a97a6029593d7dd8f))
+* non-seekable json streams would fail to load as a document ([76b0159](https://github.com/microsoft/OpenAPI.NET/commit/76b0159d12790ab00310ff107e37396ecdf13336))
+* non-seekable json streams would fail to load as a document ([2436d73](https://github.com/microsoft/OpenAPI.NET/commit/2436d7382bfbf8b9ba501d88f682e952bdf27146))
+* reading streams in an asp.net context would cause async exceptions ([f9e5248](https://github.com/microsoft/OpenAPI.NET/commit/f9e524859722476b3111cb6006f77208c2d1f526))
+
 ## [2.3.11](https://github.com/microsoft/OpenAPI.NET/compare/v2.3.10...v2.3.11) (2025-12-08)
 
 ### Bug Fixes

src/Microsoft.OpenApi/Models/OpenApiSchema.cs

@@ -264,7 +264,7 @@
         /// Initializes a copy of <see cref="IOpenApiSchema"/> object
         /// </summary>
         /// <param name="schema">The schema object to copy from.</param>
         internal OpenApiSchema(IOpenApiSchema schema)
         {
             Utils.CheckArgumentNull(schema);
             Title = schema.Title ?? Title;
@@ -341,23 +341,23 @@
             SerializeInternal(writer, OpenApiSpecVersion.OpenApi3_0, (writer, element) => element.SerializeAsV3(writer));
         }
 
         private static void SerializeBounds(IOpenApiWriter writer, OpenApiSpecVersion version, string propertyName, string exclusivePropertyName, string isExclusivePropertyName, string? value, string? exclusiveValue, bool? isExclusiveValue)
         {
             if (version >= OpenApiSpecVersion.OpenApi3_1)
             {
                 if (!string.IsNullOrEmpty(exclusiveValue) && exclusiveValue is not null)
                 {
                     // was explicitly set in the document or object model
                     writer.WritePropertyName(exclusivePropertyName);
                     writer.WriteRaw(exclusiveValue);
                 }
                 else if (isExclusiveValue == true && !string.IsNullOrEmpty(value) && value is not null)
                 {
                     // came from parsing an old document
                     writer.WritePropertyName(exclusivePropertyName);
                     writer.WriteRaw(value);
                 }
                 else if (!string.IsNullOrEmpty(value) && value is not null)
                 {
                     // was explicitly set in the document or object model
                     writer.WritePropertyName(propertyName);
@@ -366,14 +366,14 @@
             }
             else
             {
                 if (!string.IsNullOrEmpty(exclusiveValue) && exclusiveValue is not null)
                 {
                     // was explicitly set in a new document being downcast or object model
                     writer.WritePropertyName(propertyName);
                     writer.WriteRaw(exclusiveValue);
                     writer.WriteProperty(isExclusivePropertyName, true);
                 }
                 else if (!string.IsNullOrEmpty(value) && value is not null)
                 {
                     // came from parsing an old document, we're just mirroring the information
                     writer.WritePropertyName(propertyName);
@@ -435,7 +435,7 @@
             // required
             writer.WriteOptionalCollection(OpenApiConstants.Required, Required, (w, s) =>
             {
                 if (!string.IsNullOrEmpty(s) && s is not null)
                 {
                     w.WriteValue(s);
                 }
@@ -443,23 +443,39 @@
 
             // enum
             var enumValue = Enum is not { Count: > 0 }
-                && !string.IsNullOrEmpty(Const) 
+                && !string.IsNullOrEmpty(Const)
                 && version < OpenApiSpecVersion.OpenApi3_1
                 ? new List<JsonNode> { JsonValue.Create(Const)! }
                 : Enum;
             writer.WriteOptionalCollection(OpenApiConstants.Enum, enumValue, (nodeWriter, s) => nodeWriter.WriteAny(s));
 
+            // Handle oneOf/anyOf with null type for v3.0 downcast
+            IList<IOpenApiSchema>? effectiveOneOf = OneOf;
+            IList<IOpenApiSchema>? effectiveAnyOf = AnyOf;
+            bool hasNullInComposition = false;
+            JsonSchemaType? inferredType = null;
+
+            if (version == OpenApiSpecVersion.OpenApi3_0)
+            {
+                (effectiveOneOf, var inferredOneOf, var nullInOneOf) = ProcessCompositionForNull(OneOf);
+                hasNullInComposition |= nullInOneOf;
+                inferredType = inferredOneOf ?? inferredType;
+                (effectiveAnyOf, var inferredAnyOf, var nullInAnyOf) = ProcessCompositionForNull(AnyOf);
+                hasNullInComposition |= nullInAnyOf;
+                inferredType = inferredAnyOf ?? inferredType;
+            }
+
             // type
-            SerializeTypeProperty(writer, version);
+            SerializeTypeProperty(writer, version, inferredType);
 
             // allOf
             writer.WriteOptionalCollection(OpenApiConstants.AllOf, AllOf, callback);
 
             // anyOf
-            writer.WriteOptionalCollection(OpenApiConstants.AnyOf, AnyOf, callback);
+            writer.WriteOptionalCollection(OpenApiConstants.AnyOf, effectiveAnyOf, callback);
 
             // oneOf
-            writer.WriteOptionalCollection(OpenApiConstants.OneOf, OneOf, callback);
+            writer.WriteOptionalCollection(OpenApiConstants.OneOf, effectiveOneOf, callback);
 
             // not
             writer.WriteOptionalObject(OpenApiConstants.Not, Not, callback);
@@ -498,7 +514,7 @@
             // nullable
             if (version == OpenApiSpecVersion.OpenApi3_0)
             {
-                SerializeNullable(writer, version);
+                SerializeNullable(writer, version, hasNullInComposition);
             }
 
             // discriminator
@@ -771,14 +787,17 @@
             writer.WriteEndObject();
         }
 
-        private void SerializeTypeProperty(IOpenApiWriter writer, OpenApiSpecVersion version)
+        private void SerializeTypeProperty(IOpenApiWriter writer, OpenApiSpecVersion version, JsonSchemaType? inferredType = null)
         {
-            if (Type is null)
+            // Use original type or inferred type when the explicit type is not set
+            var typeToUse = Type ?? inferredType;
+
+            if (typeToUse is null)
             {
                 return;
             }
 
-            var unifiedType = IsNullable ? Type.Value | JsonSchemaType.Null : Type.Value;
+            var unifiedType = IsNullable ? typeToUse.Value | JsonSchemaType.Null : typeToUse.Value;
             var typeWithoutNull = unifiedType & ~JsonSchemaType.Null;
 
             switch (version)
@@ -809,13 +828,13 @@
         private static void WriteUnifiedSchemaType(JsonSchemaType type, IOpenApiWriter writer)
         {
             var array = (from JsonSchemaType flag in jsonSchemaTypeValues
-                        where type.HasFlag(flag)
-                        select flag.ToFirstIdentifier()).ToArray();
+                         where type.HasFlag(flag)
+                         select flag.ToFirstIdentifier()).ToArray();
             if (array.Length > 1)
             {
                 writer.WriteOptionalCollection(OpenApiConstants.Type, array, (w, s) =>
                 {
                     if (!string.IsNullOrEmpty(s) && s is not null)
                     {
                         w.WriteValue(s);
                     }
@@ -827,9 +846,9 @@
             }
         }
 
-        private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version)
+        private void SerializeNullable(IOpenApiWriter writer, OpenApiSpecVersion version, bool hasNullInComposition = false)
         {
-            if (IsNullable)
+            if (IsNullable || hasNullInComposition)
             {
                 switch (version)
                 {
@@ -843,6 +862,41 @@
             }
         }
 
+        /// <summary>
+        /// Processes a composition (oneOf or anyOf) for null types, filtering out null schemas and inferring common type.
+        /// </summary>
+        /// <param name="composition">The list of schemas in the composition.</param>
+        /// <returns>A tuple with the effective list, inferred type, and whether null is present in composition.</returns>
+        private static (IList<IOpenApiSchema>? effective, JsonSchemaType? inferredType, bool hasNullInComposition)
+            ProcessCompositionForNull(IList<IOpenApiSchema>? composition)
+        {
+            if (composition is null || !composition.Any(static s => s.Type is JsonSchemaType.Null))
+            {
+                // Nothing to patch
+                return (composition, null, false);
+            }
+
+            var nonNullSchemas = composition
+                .Where(static s => s.Type is null or not JsonSchemaType.Null)
+                .ToList();
+
+            if (nonNullSchemas.Count > 0)
+            {
+                JsonSchemaType commonType = 0;
+
+                foreach (var schema in nonNullSchemas)
+                {
+                    commonType |= schema.Type.GetValueOrDefault() & ~JsonSchemaType.Null;
+                }
+
+                return (nonNullSchemas, commonType, true);
+            }
+            else
+            {
+                return (null, null, true);
+            }
+        }
+
 #if NET5_0_OR_GREATER
         private static readonly Array jsonSchemaTypeValues = System.Enum.GetValues<JsonSchemaType>();
 #else