[OpenAPI] Invalid schema references generated

[martincostello]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

To validate the changes made in #63052 I put the OpenAPI schema into editor.swagger.io to see if the schema for JSON Patch had any validation errors (it does not).

However, amongst a few schema errors that are found in the document that aren't just artifacts of testing, I found two that appear to be actual issues:

1. Semantic error at components.schemas.Category.properties.tags.$ref - $refs must reference a valid ___location in the document from

   aspnetcore/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt

   Line 1362 in f91de94

   "$ref": "#/components/schemas/Category/properties/parent/properties/tags"

2. Semantic error at components.schemas.Item.properties.name.$ref - $refs must reference a valid ___location in the document from

   aspnetcore/src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Integration/snapshots/OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt

   Line 1427 in f91de94

   "$ref": "#/components/schemas/Root/properties/item1/properties/name"

These correlate to these parts of the code:

1. aspnetcore/src/OpenApi/sample/Endpoints/MapSchemasEndpoints.cs

   Line 51 in c103a03

   public IEnumerable<Tag> Tags { get; set; } = [];

2. aspnetcore/src/OpenApi/sample/Endpoints/MapSchemasEndpoints.cs

   Line 73 in c103a03

   public string[] Name { get; set; } = null!;

Both of these properties are arrays and appear to generate a circular reference to themselves via another object.

1. Points to the tags property of the parent property of itself, but that's also a Category, so it's just a circular reference to itself.
2. Points to the name property of the item1 property of Root, but that's also an Item, so again creates a circular reference to itself.

In both cases it looks like the schema properties should be an array of items which reference Tag or Item respectively.

Expected Behavior

The schemas do not generate validation errors.

Steps To Reproduce

Enter the contents of OpenApiDocumentLocalizationTests.VerifyOpenApiDocumentIsInvariant.verified.txt into editor.swagger.io.

Exceptions (if any)

No response

.NET Version

10.0.100-preview.7.25322.101

Anything else?

No response

[MihuBot]

Possible related and/or duplicate issues:

• OpenAPI Ref invalid when objects cycles #58915
• .NET 9 OpenAPI produces lots of duplicate schemas for the same object #58968
• Incorrect OpenAPI document generation with recursive object that contains a list #60012
• ASP.NET Core OpenAPI generator incorrectly duplicates schemas and creates invalid $ref for simple structure #60164
• OpenAPI with two collections of same type generates weird internal ref #60931

[martincostello]

Have opened #63092 to add some validation and fix some issues, plus #63095 as a draft of a test that detects this issue.

[martincostello]

This might be a runtime issue, as it looks like the reference ID gets assigned when calling JsonSchemaExporter.GetJsonSchemaAsNode() here:

aspnetcore/src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs

Lines 348 to 349 in d6f0d4b

	private JsonNode CreateSchema(OpenApiSchemaKey key)
	=> JsonSchemaExporter.GetJsonSchemaAsNode(_jsonSerializerOptions, key.Type, _configuration);

That then gets used here:

aspnetcore/src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs

Lines 222 to 223 in d6f0d4b

	var relativeSchemaId = $"#/components/schemas/{rootSchemaId}{refIdString.Replace("#", string.Empty)}";
	return new OpenApiSchemaReference(relativeSchemaId, document);

[martincostello]

Actually I don't think it is, as the reference there correctly points to the inlined schema that's generated. Looks like it needs to get fixed-up somehow to point to be a valid pointer into the OpenAPI document.

[captainsafia]

@martincostello Yep -- I had roughly root caused this as the reason for bugs like #61194 (comment). I've been marinating on a fix though since "re-rooting" the relative references that STJ creates to the OpenAPI document is trickier for relative references that are two-layers deep.