Recursive $refs in example not resolving

[lorenzo-arena]

Describe the bug

I'm trying to define and reuse some "example" defined in yaml files for multiple models, but redocly doesn't seems to resolve them correctly.

To Reproduce

Consider this openapi.yaml file:

openapi: 3.0.0
info:
  title: Test device API
  version: "0.0.1"
  description: |
    This is a test description.

servers:
  - url: /
    description: Server

paths:
  /test:
    get:
      tags:
        - Test
      summary: Test endpoint
      operationId: getTest
      responses:
        "200":
          description: The test response
          content:
            application/json:
              schema:
                $ref: ./TestSchema.yaml
              example:
                $ref: ./TestSchemaExample.yaml

components:
  schemas:
    TestSchema:
      $ref: ./TestSchema.yaml

TestSchema.yaml

type: object
properties:
  testField:
    $ref: ./TestField.yaml
  anotherField:
    $ref: ./AnotherField.yaml

TestField.yaml

type: string
description: Test String
example: "Test"

AnotherField.yaml

type: string
description: Test String
example: "Another"

I'd like to define

TestSchemaExample.yaml

testField:
  $ref: ./TestFieldExample.yaml
anotherField: "AnotherExample"

TestFieldExample.yaml

"Test"

Running

$ redocly bundle openapi.yaml --output dist/openapi.yaml --ext yaml

Results in

openapi: 3.0.0
info:
  title: Test device API
  version: 0.0.1
  description: |
    This is a test description.
servers:
  - url: /
    description: Server
paths:
  /test:
    get:
      tags:
        - Test
      summary: Test endpoint
      operationId: getTest
      responses:
        '200':
          description: The speaker preset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSchema'
              example:
                testField:
                  $ref: ./TestFieldExample.yaml
                anotherField: AnotherExample
components:
  schemas:
    TestSchema:
      type: object
      properties:
        testField:
          $ref: '#/components/schemas/TestField'
        anotherField:
          $ref: '#/components/schemas/AnotherField'
    TestField:
      type: string
      description: Test String
      example: Test
    AnotherField:
      type: string
      description: Test String
      example: Another

And the file $ref is kept for the testField example.

Expected behavior

I'd like testField in the example to resolve the assigned ref.

Redocly version(s)

2.12.5

Node.js version(s)

v22.15.0

OS, environment

Ubuntu 24.04

[tatomyr]

@lorenzo-arena, a couple of things here. First, you don't usually need to manually create components like you did in the original openapi.yaml. Redocly CLI will resolve all references from your API description and create the components section for you.

Next, resolving refs in examples is complicated in the way that we don't know whether you're referencing something or you just want your data to contain a property named $ref 🙂. That was clarified in the recent versions of OpenAPI 3.x, and values of the new examples property cannot reference anything and are treated literally. The old example behaviour remains undefined, but I wouldn't recommend using references there either. Redocly CLI simply resolves the top-level $ref, and treats all other data as an example. The following will remain the same after bundling:

              example:
                testField:
                  $ref: ./TestFieldExample.yaml # Treated as a literal property
                anotherField: 'AnotherExample'

And lastly, you don't need the --ext yaml option, it will just look at the extension of your output file 🙂.

Hope this makes sense. Feel free to clarify your use case if I missed something.