Overzealous dereferencing in bundle call

[jaeddy]

I'm working on some code to add Redoc static docs for OpenAPI specifications. I'm hoping to support a repo structure where sections of the API spec (paths, components, tags, etc.) can be kept and tracked in separate files, but merged into a single file and rendered for user-facing docs. The @redocly/openapi-cli library includes a bundle module, but it doesn't enable any control over resolving/dereferencing (cc @RomanHotsiy, Redoc maintainer and contributor to this code base... in case I'm missing or misrepresenting anything from his stack).

Alternatively, I've tried to use the $RefParser.bundle() functionality in this library to bundle API .yamls into a single file. However, I'm still not seeing the behavior I'm looking for: inserting referenced local files to the main doc, without any additional/recursive dereferencing.

---

In the YAML schema file (<rootDir>/openapi.yaml) I'm referencing with $RefParser.bundle(...), I have the following $refs, which point to local files:

components:
  schemas:
    Email:
      $ref: components/schemas/Email.yaml
    User:
      $ref: components/schemas/User.yaml

The schema in <rootDir>/components/schemas/User.yaml looks like this:

type: object
properties:
  username:
    ...
  firstName:
    ...
  lastName:
    ...
  email:
    $ref: '#/components/schemas/Email'

Based on the description of the bundle() method, I would expect the components/schemas/Users section of the output to look like this:

User:
  type: object
  properties:
    username:
      ...
    firstName:
      ...
    lastName:
      ...
    email:
      $ref: '#/components/schemas/Email'

... where the User schema is basically inserted as-is.

Instead, I get the following error message:

'Error resolving $ref pointer "<rootDir>/components/schemas/User.yaml#/components/schemas/Email".
Token "components" does not exist.

... which suggests to me that the parser is also attempting to resolve/dereference $refs in <rootDir>/components/schemas/User.yaml (contrary to the behavior I'm expecting).

---

I feel like what I'm missing is some sort of depth argument to constrain which $refs get resolved/dereferenced — e.g., only those in the primary spec. It's entirely possible I'm just overlooking something in the docs, but I'm currently stumped. Any tips or direction would be greatly appreciated.

[JamesMessinger]

$ref paths are relative to the file that they appear in, not to the root file. So #/components/schemas/Email is an invalid path in User.yaml. You should change it to one of the following instead:

Option 1: Point directly to Email.yaml

type: object
properties:
  username:
    ...
  firstName:
    ...
  lastName:
    ...
  email:
    $ref: Email.yaml      # <--- Pointing to Email.yaml in the same folder as User.yaml

Option 2: Point to the Email component in openapi.yaml

type: object
properties:
  username:
    ...
  firstName:
    ...
  lastName:
    ...
  email:
    $ref: "../../openapi.yaml#/components/schemas/Email"

[philsturgeon]

No response in a long time and seems to be working as intended.