Bundle does not resolve references in $ref siblings

[onavratil-monetplus]

Describe the bug

When bundling a schema that contains reference siblings that contain references, the references are not resolved and not included in the resulting bundle. This somehow relates to #1329 but does not involve dereferencing to reproduce.

I.e., bundle will create an invalid bundled API (missing $ref) from a valid source even without dereferencing.

To Reproduce

Use this api.yaml

openapi: 3.1.0
info:
  title: Example
  version: '0.0.1'
  description: Minimum Working Example API Spec
  contact:
    name: XY
servers:
  - url: 'http://localhost:8080'
tags:
   - name: vendors
paths:
  /sample:
    get:
      summary: Sample
      operationId: example1
      tags:
        - vendors
      responses:
        '200':
          description: A basic get example
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/test'
                # !! NOTE REFERENCE TO EXTERNAL FILE IN $ref sibling
                properties:
                  second:
                    $ref: reference.yaml
      description: sample
components:
  schemas:
    test:
      type: object
      title: test schema
      properties:
        first:
          type: integer

basically you dont even need the ref'ed reference.yaml

title: Referenced model
type: string

In any way, the result of running a simple

redocly bundle api.yaml

contains (snippet only)

     #...
      responses:
        '200':
          description: A basic get example
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/test'
                properties:
                  second:
                    $ref: reference.yaml
      description: |
     #...

Expected behavior

The reference is $ref sibling should be resolved just like any other reference

OpenAPI description

Redocly version(s)

2.25.3

Node.js version(s)

v25.5.0

OS, environment

ubuntu wsl

Additional Context

Even though redocly does not really handle $ref siblings well, its bundle capability may be used just to support some other tooling downstream that can handle siblings. However, if bundle breaks nested sibling $refs, it geneerates a problem.

[vadyvas]

Thanks a lot for reporting this and for the clear example in the issue

Could you please check whether the fix in this PR makes sense for your case?
PR: #2772

For example, with this input:

schema:
  $ref: '#/components/schemas/test'
  properties:
    second:
      $ref: reference.yaml

the bundled output should resolve sibling refs to local component refs, for example:

schema:
  $ref: '#/components/schemas/test'
  properties:
    second:
      $ref: '#/components/schemas/Second'

Also, could you clarify what you mean by:

"redocly does not really handle $ref siblings well"

Do you mean behavior for Reference Object siblings in general, or specific schema-wrapper patterns with $ref + other keywords?

According to OpenAPI 3.1 spec, Reference Object has strict rules for extra properties, so this distinction matters for expected behavior:
https://spec.openapis.org/oas/v3.1.0.html#reference-object

If you have other cases that still behave differently than expected, please share them (small examples are perfect). That would help us verify edge cases too.

[onavratil-monetplus]

Thank you kindly for the fix! It seems to solve my issue.

About my previous statement:

redocly does not really handle $ref siblings well

...I apologize, I was mistaken. I work with multiple OAS tools and probably confused it with some other tool, or with contentSchema. I made some quick tests and redocly bundle works perfectly with $ref siblings.

About $ref siblings...as far as I understand the topic, one must differentiate:

• Reference Objects defined by OAS for OAS objects
• References in JSON schema (which is what you probably call "specific schema-wrapper patterns with $ref + other keywords")

The first, as you mentioned, only allows summary and desription "overrides" as $ref siblings as you quoted.

However, those elements of OAS that refer to data schemas, are not defined by OAS, but by JSON Schema draft

4.8.24.1 Properties
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 2020-12.

For more information about the properties, see JSON Schema Core and JSON Schema Validation.

Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.

...and this is what JSON schema says about $ref:

8.2.3.1. Direct References with "$ref"

The "$ref" keyword is an applicator that is used to reference a
statically identified schema. Its results are the results of the
referenced schema. [[CREF5: Note that this definition of how the
results are determined means that other keywords can appear alongside
of "$ref" in the same schema object. ]]

If this holds, then we are in agreement.