.NET 9 OpenAPI produces lots of duplicate schemas for the same object

[ascott18]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

A very simple circular/recursive data model produces a ton of duplicate schema definitions like Object, Object2, Object3, Object4, and so on.

Expected Behavior

Each class in C# is represented in the OpenAPI schema only once, as was the case with Swashbuckle.

Steps To Reproduce

• Brand new .NET 9 Web API from template, with OpenAPI enabled.
• Replace WeatherForecastController:

    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        [HttpGet("GetParent")]
        public ParentObject GetParent() => new();

        [HttpGet("GetChild")]
        public ChildObject GetChild() => new();
    }

    public class ParentObject
    {
        public int Id { get; set; }
        public List<ChildObject> Children { get; set; } = [];
    }

    public class ChildObject
    {
        public int Id { get; set; }
        public ParentObject? Parent { get; set; }
    }

• Launch app
• Look at /openapi/v1.json
• Observe ChildObject2, ParentObject2, ParentObject3, which shouldn't exist.

{
  "openapi": "3.0.1",
  "info": {
    "title": "aspnet9api | v1",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://localhost:7217"
    },
    {
      "url": "http://localhost:5067"
    }
  ],
  "paths": {
    "/WeatherForecast/GetParent": {
      "get": {
        "tags": [
          "WeatherForecast"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ParentObject"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParentObject"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParentObject"
                }
              }
            }
          }
        }
      }
    },
    "/WeatherForecast/GetChild": {
      "get": {
        "tags": [
          "WeatherForecast"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ChildObject2"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChildObject2"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChildObject2"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ChildObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "parent": {
            "$ref": "#/components/schemas/ParentObject2"
          }
        }
      },
      "ChildObject2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "parent": {
            "$ref": "#/components/schemas/ParentObject3"
          }
        }
      },
      "ParentObject": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChildObject"
            }
          }
        }
      },
      "ParentObject2": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "children": {
            "$ref": "#/components/schemas/#/properties/children"
          }
        },
        "nullable": true
      },
      "ParentObject3": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int32"
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChildObject"
            }
          }
        },
        "nullable": true
      }
    }
  },
  "tags": [
    {
      "name": "WeatherForecast"
    }
  ]
}

.NET Version

9.0.100

Anything else?

In my real-world application, the worst offending model has been duplicated 39 times:

[fredriks-eltele]

Did some fiddling as we too meet this problem, but without circular references.

Crafted the most minimal repro I could:

[ApiController]
[Route("[controller]")]
public class BadSchemaController : ControllerBase
{
    public record Root(Branch Prop1, Branch Prop2, Branch Prop3);
    public record Branch(Thing Thing);
    public record Thing();
    [HttpGet(Name = "GetBadSchema")]
    public Root Get() => throw new NotImplementedException();
}

This results in the type Branch2, which is used by Prop2 and Prop3.
Interestingly, if public record Branch(Thing Thing) is replaced by public record Branch(string StringThing), the problem does not occur.

.NET 9.0.100 with <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.0" />

[fredriks-eltele]

Okay so OpenaApiSchemaService.CreateSchema calls into System.Text.Json.JsonSchemaExporter.GetJsonSchemaAsNode, which calls MapJsonSchemaCore.

During processing of Prop1, everything goes normally and we get a {Type = Branch, Kind = Object}.
Subsequent processing will short-circuit in MapJsonSchemaCore since state.TryGetExistingJsonPointer() will succeed, so new JsonSchema { Ref = existingJsonPointer } is returned. Type is never changed, so it defaults to JsonSchemaType.Any, which at some point becomes null back in OpenApi-land.

Back in the OpenApiSchemaService when trying to add Prop2, equality is checked with OpenApiSchemaComparer.Equals (OpenApiSchemaStore.AddOrUpdateSchemaByReference() {... if (SchemasByReference.TryGetValue(schema, out var referenceId) || captureSchemaByRef) ... } where SchemasByReference has the schema comparer as its equality comparer)

The very first check after null-checks and reference equality checks in OpenApiSchemaComparer.Equals is x.Type == y.Type. This fails since "object" == null is false), the objects are deemed not the same, and SchemasByReference[schema] = $"{targetReferenceId}{counter}" puts us in duplicate-land.

I'm not sure if this actually points in the right direction towards a solution (naïve idea being to set the Type when returning the Ref JsonSchema), I was just bored during my lunch break and wanted to look a bit deeper into it.

[csteenbock]

I am also seeing this behavior. I've noticed that the duplicates aren't perfectly identical either. You can see that teachers and students are correct for one of these, while principal is correct for the other. BTW, this generated schemas for 6 different SchoolDtos...

"SchoolDto": {
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "principal": {
      "$ref": "#/components/schemas/PrincipalDto"
    },
    "streetAddress": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "state": {
      "type": "string"
    },
    "zipCode": {
      "type": "string"
    },
    "teachers": {
      "$ref": "#/components/schemas/#/items/properties/teacher/properties/school/properties/principal/properties/school/properties/teachers"
    },
    "students": {
      "$ref": "#/components/schemas/#/items/properties/teacher/properties/school/properties/principal/properties/school/properties/students"
    }
  },
  "nullable": true
},
"SchoolDto2": {
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "principal": {
      "$ref": "#/components/schemas/#/items/properties/teacher/properties/school/properties/principal"
    },
    "streetAddress": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "state": {
      "type": "string"
    },
    "zipCode": {
      "type": "string"
    },
    "teachers": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/TeacherDto2"
      }
    },
    "students": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/#/items"
      }
    }
  },
  "nullable": true
}

[gedbac]

Same problem inside Azure-Samples/eShopOnAzure. Nested types are not treated as same types.

[akamor]

We see it as well. Interestingly, we can make the problem go away if we remove our Description attribute from above each property which uses the type being duplicated. I mention this because I haven't seen anyone else mention it.

public abstract class Model
{
    public SomeEnum GeneratorDefault { get; set; } = SomeEnum.Value1;

    public SomeEnum OtherGeneratorDefault { get; set; } = SomeEnum.Value2;
}

yields a single schema object for SomeEnum. If we add a [Description()] for both properties then all of a suddent we get two schema objects, one called SomeEnum and the other called SomeEnum1.

Anyone have a reasonable workaround for this?

[akamor]

Has anyone come up with a viable workaround here? I was planning on addressing it with a DocumentTransformer but unfortunately the Document transformer, while it is called after my schema transformers, does not seem to have access to the schema objects.

document.Components.Schemas

remains empty when the DocumentTranformer.TransformAsync is invoked.

[mikekistler]

I also encountered this problem in eShop. In that case and maybe others it seems to come down to a difference in the "nullable" attribute in two uses of the schema. When the schema is for a property, it is marked as "nullable: true" because System.Text.Json accepts the value "null" and treats it as "not provided". When the schema is for the "items" of an array, "null" is not allowed so the schema defaults to "nullable: false".

I found that I could fix the duplicate schema problem in eShop with a schema transformer that removes nullable: true from any properties that are "optional" (not listed in the "required" keyword of the schema). The transformer is pretty small so I'll just include the code here in case anyone else wants to try it:

    options.AddSchemaTransformer((schema, context, cancellationToken) =>
    {
        if (schema.Properties is not null)
        {
            foreach (var property in schema.Properties)
            {
                if (schema.Required?.Contains(property.Key) != true)
                {
                    property.Value.Nullable = false;
                }
            }
        }
        return Task.CompletedTask;
    });

[motuzko]

Same here with minimal API:

https://github.com/motuzko/open-api-bug

As the result, a set of duplicate entities (CurrencyValuesWithUsd/CurrencyValuesWithUsd2) is generated in the OpenAPI spec

[emiliovmq]

Hi, any viable solution here? We're dealing with the same issue here. If we do:

/// <summary>
/// Defines the staff information.
/// </summary>
[Description("Defines the staff information.")]
public sealed class Staff
{
    /// <summary>
    /// Gets the staff identifier.
    /// </summary>
    [Description("The staff identifier.")]
    [JsonRequired]
    [Required]
    public int Id { get; init; }

    /// <summary>
    /// Gets the staff first name.
    /// </summary>
    [Description("The staff first name.")]
    [JsonRequired]
    [Required]
    [MaxLength(30)]
    public string FirstName { get; init; } = default!;

    /// <summary>
    /// Gets the staff middle name.
    /// </summary>
    [Description("The staff middle name.")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [MaxLength(30)]
    public string? MiddleName { get; init; }

    /// <summary>
    /// Gets the staff last name.
    /// </summary>
    [Description("The staff last name.")]
    [JsonRequired]
    [Required]
    [MaxLength(30)]
    public string LastName { get; init; } = default!;

    /// <summary>
    /// Gets the position code.
    /// </summary>
    [Description("The position code.")]
    [JsonRequired]
    [Required]
    [MaxLength(3)]
    public string PositionCode { get; init; } = default!;

    /// <summary>
    /// Gets the position name.
    /// </summary>
    [Description("The position name.")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [MaxLength(30)]
    public string? PositionName { get; init; }

    /// <summary>
    /// Gets a value indicating whether the position is for a manager or not.
    /// </summary>
    [Description("A value indicating whether the position is for a manager or not.")]
    [JsonRequired]
    [Required]
    public bool IsManager { get; init; }
}

it works!!! It generates only one scheme for Staff

"Staff": {
        "required": [
          "id",
          "firstName",
          "lastName",
          "positionCode",
          "isManager"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The staff identifier.",
            "format": "int32"
          },
          "firstName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff first name."
          },
          "middleName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff middle name.",
            "nullable": true
          },
          "lastName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff last name."
          },
          "positionCode": {
            "maxLength": 3,
            "type": "string",
            "description": "The position code."
          },
          "positionName": {
            "maxLength": 30,
            "type": "string",
            "description": "The position name.",
            "nullable": true
          },
          "isManager": {
            "type": "boolean",
            "description": "A value indicating whether the position is for a manager or not."
          }
        },
        "description": "Defines the staff information."
      },

But if we do (as it should be, not the other way):

/// <summary>
/// Defines the position.
/// </summary>
[Description("Defines the position.")]
public sealed class Position
{
    /// <summary>
    /// Gets the position code.
    /// </summary>
    [Description("The position code.")]
    [JsonRequired]
    [Required]
    [MaxLength(3)]
    public string Code { get; init; } = default!;

    /// <summary>
    /// Gets the position name.
    /// </summary>
    [Description("The position name.")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [MaxLength(30)]
    public string? Name { get; init; }

    /// <summary>
    /// Gets a value indicating whether the position is for a manager or not.
    /// </summary>
    [Description("A value indicating whether the position is for a manager or not.")]
    [JsonRequired]
    [Required]
    public bool IsManager { get; init; }
}

/// <summary>
/// Defines the staff information.
/// </summary>
[Description("Defines the staff information.")]
public sealed class Staff
{
    /// <summary>
    /// Gets the staff identifier.
    /// </summary>
    [Description("The staff identifier.")]
    [JsonRequired]
    [Required]
    public int Id { get; init; }

    /// <summary>
    /// Gets the staff first name.
    /// </summary>
    [Description("The staff first name.")]
    [JsonRequired]
    [Required]
    [MaxLength(30)]
    public string FirstName { get; init; } = default!;

    /// <summary>
    /// Gets the staff middle name.
    /// </summary>
    [Description("The staff middle name.")]
    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
    [MaxLength(30)]
    public string? MiddleName { get; init; }

    /// <summary>
    /// Gets the staff last name.
    /// </summary>
    [Description("The staff last name.")]
    [JsonRequired]
    [Required]
    [MaxLength(30)]
    public string LastName { get; init; } = default!;

    /// <summary>
    /// Gets the position.
    /// </summary>
    [JsonRequired]
    [Required]
    public Position Position { get; init; } = default!;
}

It does not work; 2 schemes are generated for Staff

"Position": {
        "required": [
          "code",
          "isManager"
        ],
        "type": "object",
        "properties": {
          "code": {
            "maxLength": 3,
            "type": "string",
            "description": "The position code."
          },
          "name": {
            "maxLength": 30,
            "type": "string",
            "description": "The position name.",
            "nullable": true
          },
          "isManager": {
            "type": "boolean",
            "description": "A value indicating whether the position is for a manager or not."
          }
        },
        "description": "Defines the position."
      },
"Staff": {
        "required": [
          "id",
          "firstName",
          "lastName",
          "position"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The staff identifier.",
            "format": "int32"
          },
          "firstName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff first name."
          },
          "middleName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff middle name.",
            "nullable": true
          },
          "lastName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff last name."
          },
          "position": {
            "$ref": "#/components/schemas/Position"
          }
        },
        "description": "Defines the staff information."
      },
      "Staff2": {
        "required": [
          "id",
          "firstName",
          "lastName",
          "position"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The staff identifier.",
            "format": "int32"
          },
          "firstName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff first name."
          },
          "middleName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff middle name.",
            "nullable": true
          },
          "lastName": {
            "maxLength": 30,
            "type": "string",
            "description": "The staff last name."
          },
          "position": {
            "$ref": "#/components/schemas/#/properties/details/items/properties/staff/properties/position"
          }
        },
        "description": "Defines the staff information."
      }

Any idea?

[ascott18]

@captainsafia Sorry for the ping, but I know you worked a lot on the OpenAPI stuff. Wasn't sure if you'd seen this yet - it essentially makes the entire feature completely unusable beyond the most trivial applications.