[Youssef Fahmy (Youssef1313)]

Fixes #2939

• The change to ToSingleIdentifier is only a simplification to make it easier to read.
• Type serialization is now split to two path to be easier to read, especially that 3.0 needs more parameters/info than 2.0.
• The behavior of 2.0 is maintained as-is, no change there
• Previously, in 3.0, we ignored when Type had multiple values (e.g, String and Integer). This is now handled using oneOf or anyOf (whichever isn't used by the current schema already). If both are used, we ignore as it we used to in the past.
• The general idea here is:
  1. We take the Type.
  2. We remove Null from it (if it exists).
  3. If, after removing null, we have a single type, we simply emit it, and conditionally emit nullable: true depending on whether null was existing. This is the same as the existing behavior.
  4. If, after removing null, we have more than one type, we create a oneOf/anyOf with children schemas handling each type individually.
• The reason around all that is that because type only supports a single value when using OpenApi 3.0.

For context: https://spec.openapis.org/oas/v3.0.4.html#json-schema-keywords

The following keywords are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.
type - Value MUST be a string. Multiple types via an array are not supported.

[Vincent Biret (baywet)]

I believe this kind of normalization should not be done during serialization, but rather through a walker which would be called before serialization.

See #808 and other related issues.

Case in point, we've had to revert some of the normalization done for null/nullable (to oneOf) in #2933

[Copilot]

Pull request overview

This pull request updates OpenApiSchema JSON serialization to properly represent schemas with multiple JsonSchemaType flags when targeting OpenAPI 3.0, emitting anyOf/oneOf (when possible) instead of silently ignoring additional types, and adds coverage to validate the new behavior.

Changes:

• Split type serialization logic between OpenAPI 2.0 and OpenAPI 3.0+ paths, adding 3.0-specific handling for multi-type schemas via anyOf/oneOf.
• Add comprehensive unit tests covering multi-type combinations (with/without null, and with existing oneOf/anyOf present).
• Simplify ToSingleIdentifier by using a lookup and providing a clearer exception for unexpected values.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaTests.cs	Adds tests validating multi-type serialization behavior for OpenAPI 3.0 across multiple composition scenarios.
src/Microsoft.OpenApi/Models/OpenApiSchema.cs	Refactors and extends type serialization to support multi-type handling in 3.0 using anyOf/oneOf, keeping 2.0 behavior unchanged.
src/Microsoft.OpenApi/Extensions/OpenApiTypeMapper.cs	Updates ToSingleIdentifier to use a lookup and throw a clearer exception for unexpected inputs.

Comments suppressed due to low confidence (1)

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1091

• In the v3.1+ path, TrySerializeTypePropertyForVersion3AndLater also assumes Enum.GetValues() will match at least one flag in the provided Type. If Type is 0 or contains only unknown bits, array will be empty and array[0] will throw IndexOutOfRangeException. Add an empty-array guard and return false when no valid flags are present.

                var array = (from JsonSchemaType flag in jsonSchemaTypeValues
                                        where type.HasFlag(flag)
                                        select flag).ToArray();

                if (array.Length > 1)
                {
                    writer.WriteOptionalCollection(OpenApiConstants.Type, array, (w, s) => w.WriteValue(s.ToSingleIdentifier()));
                }
                else
                {
                    writer.WriteProperty(OpenApiConstants.Type, array[0].ToSingleIdentifier());
                }

[Youssef Fahmy (Youssef1313)]

I believe this kind of normalization should not be done during serialization, but rather through a walker which would be called before serialization.

Given the investigations I did for #2967, I think it's fine for us to continue ensuring, as much as possible, that we produce semantically equivalent document for all versions. The cases presented in #2967 fall into two groups:

• user bug (e.g, the Swashbuckle bug, or the JsonApiDotNetCore bug)
• deserialization bugs on our side, which we can simply fix.

I don't believe there is a need for a new public API to do the semantic transformations, and I don't think all transformations we might want to do in future will be representable in the object model. So we will end up with logic scattered between dedicated walkers and in the serialization itself. We shouldn't need to pay additional performance cost for deep cloning the whole document as well.

In all cases, we can always decide to move the logic to a walker in the future, if really necessary.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Suppressed comments (4)

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1088

• In the OpenAPI 3.1+ branch, array[0] is used when array.Length <= 1. If Type is 0 or contains no known flags, array will be empty and this will throw IndexOutOfRangeException.

                }
                else
                {
                    writer.WriteProperty(OpenApiConstants.Type, array[0].ToSingleIdentifier());
                }

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1073

• arrayWithoutNull[0] is accessed without guarding for arrayWithoutNull.Length == 0. If Type is set to an unexpected value (e.g., 0 / no flags, or only unknown bits), this will throw IndexOutOfRangeException during OpenAPI 3.0 serialization.

                else
                {
                    writer.WriteProperty(OpenApiConstants.Type, arrayWithoutNull[0].ToSingleIdentifier());
                    return;
                }

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1053

• For OpenAPI 3.0, when Type includes null and multiple non-null types, this path represents null by adding a child schema with Type = Null into anyOf/oneOf. However SerializeNullable will still emit top-level nullable: true whenever HasNullType is true, even though there is no top-level type in that case. This produces redundant/ineffective output and contradicts the new tests that expect no nullable when null is represented via anyOf/oneOf.

This issue also appears in the following locations of the same file:

• line 1069
• line 1084

                // - If we have more than one type (excluding null), we have to use anyOf/oneOf.
                // - If we have exactly one type alone (without null), we emit the type property.
                // - If we have exactly one non-null type and also we have the null type, we emit the type property and nullable: true (handled in SerializeNullable)
                if (arrayWithoutNull.Length > 1)

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1029

• This XML doc uses a <returns> block, but the method returns void. Either remove the <returns> documentation or change the method signature to return a value (and use it at the call site).

        /// <returns>
        /// true if the Type was serializable using "type" property, and false if
        /// it serialized using anyOf/oneOf or if it couldn't be serialized at all.
        /// </returns>

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (5)

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaV30CompatibilityTests.cs:147

• The test name says it "OmitsType", but the updated expected JSON now writes multiple types via anyOf (and also keeps nullable). Renaming the test would better match the behavior being asserted.

        public async Task SerializeMultipleNonNullTypesWithNullAsV3OmitsTypeButKeepsNullable()

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1029

• XML documentation has a section describing a boolean return value, but SerializeTypePropertyForVersion3AndLater returns void. This makes the docs misleading for future maintainers.

        /// <summary>
        /// Tries to serialize the "type" property for OpenAPI v3 and later versions.
        /// </summary>
        /// <returns>
        /// true if the Type was serializable using "type" property, and false if
        /// it serialized using anyOf/oneOf or if it couldn't be serialized at all.
        /// </returns>

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1048

• For OpenAPI 3.0, if Type is set to an empty flags value (e.g., (JsonSchemaType)0), typeWithoutNull will produce no flags and arrayWithoutNull will be empty. The current code then falls into the single-type branch and indexes arrayWithoutNull[0], which will throw IndexOutOfRangeException.

                var typeWithoutNull = type & ~JsonSchemaType.Null;
                var hasNull = typeWithoutNull != type;
                var arrayWithoutNull = (from JsonSchemaType flag in jsonSchemaTypeValues
                                        where typeWithoutNull.HasFlag(flag)
                                        select flag).ToArray();

src/Microsoft.OpenApi/Models/OpenApiSchema.cs:1079

• For OpenAPI versions other than 3.0, if Type is an empty flags value ((JsonSchemaType)0), the computed array will be empty and the code will index array[0], throwing IndexOutOfRangeException.

                var array = (from JsonSchemaType flag in jsonSchemaTypeValues
                                        where type.HasFlag(flag)
                                        select flag).ToArray();

test/Microsoft.OpenApi.Tests/Models/OpenApiSchemaV30CompatibilityTests.cs:121

• The test name says it "OmitsType", but the updated expected JSON now writes multiple types via anyOf. Renaming the test would keep intent clear and avoid future confusion.

This issue also appears on line 147 of the same file.

        public async Task SerializeMultipleNonNullTypesAsV3OmitsType()