Skip to content

[BUG] [OpenAPI 3.1] siblings of $ref are lost #20304

Closed

Description

@Felk

Bug Report Checklist

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:

components:
  schemas:
    ModelWithTitledProperties:
      properties:
        refProperty:
          type: string
          title: Ref-Property-Title
          $ref: '#/components/schemas/RefObject'
      type: object
    RefObject:
      type: string

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

export const {{classname}}Meta = {
{{#vars}}
    {{name}}: {
        title: `{{{title}}}`,
        description: `{{{description}}}`
    },
{{/vars}}
} as const;

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

Activity

  1. FrankShaw commented on Mar 19, 2025

    @FrankShaw

    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.

  2. Felk commented on Jun 4, 2025

    @Felk
    ContributorAuthor

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

  3. FrankShaw commented on Jun 5, 2025

    @FrankShaw

    @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

  4. added 2 commits that reference this issue on Jul 28, 2025
  5. wing328 commented on Nov 17, 2025

    @wing328
    Member

    update: I've filed #22364 to fix the issue. if when you've time, please kindly do a test.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions