Wrong header output when running `redocly bundle`

[tandiljuan]

Describe the bug

Using my files, when running the bundle (sub) command, the bundled output is not well formed. There is a header that looks like:

X-Location:
  $ref: components.yaml#/components/headers/created_url

But it should look like:

X-Location:
  $ref: '#/components/headers/created_url'

The reference worked on other files, but it failed in the file that was used twice.

I tried to replicate the bug with a simple and small demo without success. That's why I'm sharing the repository where it's failing.

• file: routehub/deliveries.yaml
• line: 216

To Reproduce

1. Clone the repository from: https://github.com/tandiljuan/routehub-openapi/tree/error_bundle
2. npm install
3. npm run bundle-yaml

Expected behavior

X-Location:
  $ref: '#/components/headers/created_url'

Redocly version(s)

2.12.6

Node.js version(s)

• node: 24.9.0
• npm: 11.6.0

OS, environment

Linux

[vadyvas]

@tandiljuan Thanks for the detailed report and the reproducible repo.

One important note: in OpenAPI 3.1 a $ref is a Reference Object. A Reference Object cannot be combined with arbitrary sibling properties — it may only contain $ref and (in 3.1) optionally summary / description https://spec.openapis.org/oas/v3.1.0.html#reference-object. If you need additional fields (e.g., schema/content/headers/ etc.), those must live in the referenced component, or you need to model it differently.

For your specific case, a spec-compliant structure would be to reference reusable components at the points where the spec allows a Reference Object https://spec.openapis.org/oas/v3.1.0.html#response-object, e.g.:

"201":
  description: Bundle created.
  headers:
    X-Location:
      $ref: "components.yaml#/components/headers/created_url"
  content:
    application/json:
      schema:
        $ref: "#/components/schemas/delivery_get"
      examples:
        $ref: "deliveries_examples.yaml#/unit/200"

Regarding the bundling output: we agree that bundle should not output broken/unresolvable reference. We’ll take a closer look at why this particular $ref ends up as components.yaml#/... in the bundled output.

[tandiljuan]

Hi @vadyvas . Thanks a lot for the quick reply and explanation. Have a great day!