[OpenAPI] Invalid schema references generated

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:

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"
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:

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

Line 51 in c103a03

public IEnumerable<Tag> Tags { get; set; } = [];
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.

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.
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

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

[OpenAPI] Validate OpenAPI documents

[OpenApi] Test schema reference validity

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

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);

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.

@martincostello

@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.

[OpenAPI] Validate OpenAPI documents

[OpenApi] Test schema reference validity

[OpenAPI] Validate OpenAPI documents

[OpenApi] Test schema reference validity

Looks like #63256 fixed this. #63092 should now pass and help detect any recurrence in the future.

[OpenAPI] Validate OpenAPI documents (#63092)

Navigation Menu

Repository navigation

[OpenAPI] Invalid schema references generated #63090

Is there an existing issue for this?

Describe the bug

Expected Behavior

Steps To Reproduce

Exceptions (if any)

.NET Version

Anything else?

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

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

[OpenAPI] Invalid schema references generated #63090

Description

Is there an existing issue for this?

Describe the bug

Expected Behavior

Steps To Reproduce

Exceptions (if any)

.NET Version

Anything else?

Activity

MihuBot commented on Aug 4, 2025

martincostello commented on Aug 4, 2025

martincostello commented on Aug 4, 2025

martincostello commented on Aug 4, 2025

captainsafia commented on Aug 4, 2025

martincostello commented on Aug 15, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions