Why does the OpenAPI generator generate anyOf and not oneOf for polymorphic types?

[lvde0]

Given the following hierarchy:

[JsonPolymorphic(TypeDiscriminatorPropertyName = "petType")]
[JsonDerivedType(typeof(Horse), "Horse")]
[JsonDerivedType(typeof(Pig), "Pig")]
abstract record Pet(string Name);

record Horse(string Name) : Pet(Name);

record Pig(string Name) : Pet(Name);

it generates:

"components": {
  "schemas": {
    "Pet": {
      "required": [
        "petType"
      ],
      "type": "object",
      "anyOf": [
        {
          "$ref": "#/components/schemas/PetHorse"
        },
        {
          "$ref": "#/components/schemas/PetPig"
        }
      ],
      "discriminator": {
        "propertyName": "petType",
        "mapping": {
          "Horse": "#/components/schemas/PetHorse",
          "Pig": "#/components/schemas/PetPig"
        }
      }
    },
    "PetHorse": {
      "required": [
        "name"
      ],
      "properties": {
        "petType": {
          "enum": [
            "Horse"
          ],
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "PetPig": {
      "required": [
        "name"
      ],
      "properties": {
        "petType": {
          "enum": [
            "Pig"
          ],
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      }
    }
  }
},

Wouldn't oneOf make more sense here? Pet can be exactly Pig or Horse, but not both.

[MentalOfCrow]

oneOf is a reasonable representation for this specific hierarchy, but the generated anyOf is deliberate and is not weaker in practice for the schema shown.

ASP.NET Core obtains the initial JSON Schema from the System.Text.Json schema exporter. That exporter always models a polymorphic hierarchy with anyOf; the implementation says so explicitly and then creates one branch per configured derived type:

https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/System/Text/Json/Schema/JsonSchemaExporter.cs#L88-L178

ASP.NET Core subsequently maps the JsonPolymorphic metadata to the OpenAPI discriminator and component references, while preserving that anyOf structure:

https://github.com/dotnet/aspnetcore/blob/main/src/OpenApi/src/Extensions/JsonNodeSchemaExtensions.cs#L428-L470

The important semantic difference is:

• anyOf: the instance must match at least one branch;
• oneOf: the instance must match exactly one branch.

In your generated schema, petType is required and each branch constrains it to a different single value (Horse or Pig). Therefore an instance cannot validate against both branches. For this hierarchy, anyOf and oneOf accept the same instances, so the generated schema is already unambiguous.

The exporter uses anyOf generically because not every .NET polymorphic configuration proves that its branches are mutually exclusive. For example, derived schemas can structurally overlap, discriminators can be absent in some supported System.Text.Json configurations, and a non-abstract base type can itself be serializable. Emitting oneOf universally would reject instances that legitimately match multiple structural branches.

If a particular client generator requires oneOf, and you control the hierarchy and know that every branch has a required, unique discriminator, you can change only that schema with an OpenAPI schema transformer:

builder.Services.AddOpenApi(options =>
{
    options.AddSchemaTransformer((schema, context, cancellationToken) =>
    {
        if (context.JsonTypeInfo.Type == typeof(Pet) &&
            schema.AnyOf is { Count: > 0 })
        {
            schema.OneOf = schema.AnyOf;
            schema.AnyOf = null;
        }

        return Task.CompletedTask;
    });
});

Schema transformers are the supported customization point:
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi

I would keep the default unless a downstream tool specifically needs oneOf. If you do transform it, retain the discriminator and apply the change only to hierarchies whose alternatives are demonstrably exclusive.

If this explains the generated result and solves the interoperability concern, you can mark it as the accepted answer so future readers can find the distinction quickly.