You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[BUG] [OpenAPI 3.1] siblings of $ref are lost #20304
What's the actual output vs expected output? -> see the test
[Optional] Sponsorship to speed up the bug fix or feature request (example)
Description
Starting with OpenAPI 3.1, it is allowed for $ref-objects to have sibling properties and those sibling properties should not be lost. A simple example would be:
Expected: when generating code, I have access to refProperty's title field.
Reality: The value of title (and other fields, such as description) are lost.
For example, if I try to generate TypeScript code that includes a model's title using a custom template (but the issue is not TypeScript-specific):
this works for regular properties, but title and description are always empty for properties that include a $ref.
openapi-generator version
7.10.0 (actually latest master, d29196a).
As far as I understand, this is not a regression, but just a yet undetected bug for OpenAPI 3.1 schemas.
Steps to reproduce
I opened a complimentary pull request that adds a test case showcasing the problem: #20303
Suggest a fix
Best lead I found while debugging was that ModelUtils#unaliasSchema seems to just 100% forward the $ref'ed schema if it detects a ref that doesn't fall into one of the special cases like isObjectSchema(...).
For reference, the only sibling fields allowed for ReferenceObjects in OAS 3.1.X are summary and description. If your spec has these fields, it is a bug that they are ignored. But, in your example, type and title are not valid fields for a ReferenceObject so they should be ignored by the parser.
@FrankShaw are you sure about that restriction? I thought the same initially too, but got some more context here: swagger-api/swagger-parser#2036 (comment) (see the linked comment and the comment after that one)
@Felk you are right. The restriction I mentioned is enforced in every other area of an OpenAPI 3.1 specification, but in the schemas section that follows the SchemaObject model which is based on the JSON Schema Draft 2020-12 which does not have any restrictions on sibling fields for objects using a $ref
Activity
FrankShaw commentedon Mar 19, 2025
For reference, the only sibling fields allowed for ReferenceObjects in OAS 3.1.X are
summaryanddescription. If your spec has these fields, it is a bug that they are ignored. But, in your example,typeandtitleare not valid fields for a ReferenceObject so they should be ignored by the parser.Felk commentedon Jun 4, 2025
@FrankShaw are you sure about that restriction? I thought the same initially too, but got some more context here: swagger-api/swagger-parser#2036 (comment) (see the linked comment and the comment after that one)
FrankShaw commentedon Jun 5, 2025
@Felk you are right. The restriction I mentioned is enforced in every other area of an OpenAPI 3.1 specification, but in the
schemassection that follows the SchemaObject model which is based on the JSON Schema Draft 2020-12 which does not have any restrictions on sibling fields for objects using a$reffix: issue OpenAPITools#20304 - map siblings (from OAS 3.1) correctly…
fix: issue OpenAPITools#20304 - map siblings (from OAS 3.1) correctly…
wing328 commentedon Nov 17, 2025
update: I've filed #22364 to fix the issue. if when you've time, please kindly do a test.