Repository navigation
Description
Firstly please note this is an issue found and reproduced by Claude Code (Opus 4.8).
Describe the bug
When parsing a split-file OpenAPI 3.1 document with LoadExternalRefs = true, the reader throws InvalidOperationException: Circular reference detected while resolving schema: ... for a schema that is not circular.
The trigger is this pattern:
- A root document's
components/schemas/Xentry is itself a pass-through$refto a schema in an external file (i.e.X: { $ref: './shared.yaml#/X' }— a re-export), and - That same external schema is also referenced directly from somewhere else (e.g. a path operation's response schema).
The resolver appears to treat the root re-export ref plus the direct ref to the same external target as a cycle, even though the target schema is a plain leaf with no outgoing $refs.
OpenApi File To Reproduce
root.yaml
openapi: 3.1.0
info: { title: T, version: 1.0.0 }
paths:
/a:
get:
responses:
'200':
description: ok
content:
application/json:
schema:
type: object
properties:
meta: { $ref: './shared.yaml#/Leaf' }
components:
schemas:
Leaf:
$ref: './shared.yaml#/Leaf' # root pass-through re-exportshared.yaml
Leaf:
type: object
properties:
x: { type: string }
y: { type: integer }Program.cs
using Microsoft.OpenApi;
using Microsoft.OpenApi.Reader;
using Microsoft.OpenApi.YamlReader;
var path = "/abs/path/to/root.yaml";
var settings = new OpenApiReaderSettings { LoadExternalRefs = true, BaseUrl = new Uri(path) };
settings.AddYamlReader();
var result = await OpenApiDocument.LoadAsync(path, settings);
Console.WriteLine($"Paths={result.Document?.Paths?.Count}, Errors={result.Diagnostic?.Errors?.Count}");System.InvalidOperationException: Circular reference detected while resolving schema: ./shared.yaml#/Leaf
Expected behavior
The document parses successfully. Leaf is a leaf schema with no outgoing references and is not part of any cycle.
Additional context
-
Removing the root
components/schemas/Leafpass-through ref (keeping only the direct ref from the path) parses fine, so the pass-through re-export appears to be the trigger. -
A leaf schema referenced from multiple paths (but without the root re-export) also parses fine.
-
Microsoft.OpenApi3.6.0 -
Microsoft.OpenApi.YamlReader3.6.0 -
net10.0
Activity
baywet commentedon Jun 9, 2026
Hi Alex Angas (@alexangas),
Thank you for using the SDK and for reaching out.
I've put #2873 together, please have a look whenever you have time.
Let me know if you have any additional comments or questions.
fix(library): avoid false circular refs for external schema re-exports