packages/openapi-ts/README.md
Clone this repository
For self-hosted knots, clone URLs may differ based on your setup.
Download tar.gzfix: surface actual error message when spec fetch fails
Cover the fallback resolution and crawl path rebase fixes in
inventory$Ref with five scenarios: bare wrapper chain, extended
wrapper chain, direct reference (no wrapper), multiple siblings
through an extended wrapper, and collision handling when two
external files expose same-named sibling schemas.
Signed-off-by: Jason Westover <jwestover@nvidia.com>
Co-authored-by: mrlubos <12529395+mrlubos@users.noreply.github.com>
Co-authored-by: mrlubos <12529395+mrlubos@users.noreply.github.com>
Use unprefixed schema names from external files unless conflicts exist
Ran `pnpm test:update` to regenerate all test snapshots after implementing conditional schema name prefixing. External schemas now use unprefixed names (e.g., "Foo") instead of prefixed names (e.g., "external_Foo") when there are no naming conflicts.
This affects all OpenAPI test snapshots across 2.0.x, 3.0.x, and 3.1.x versions.
Co-authored-by: mrlubos <12529395+mrlubos@users.noreply.github.com>
When `$RefParser.bundle()` processes external files that use wrapper/redirect patterns (common in DMTF Redfish and similar large-scale OpenAPI specs), sibling schemas within versioned files are not hoisted into the root spec. This produces dangling `$ref` pointers and "Skipping unresolvable $ref" warnings.
**Affects:** 35 schemas lost when bundling the [DMTF Redfish OpenAPI spec](https://github.com/DMTF/Redfish-Publications/blob/main/openapi/openapi.yaml).
The bundler's crawl path retains the **wrapper file** URL as context when traversing the resolved schema's properties. When a local `$ref` like `#/components/schemas/SiblingSchema` is encountered inside the resolved schema, `url.resolve()` resolves it against the wrapper file — which doesn't contain the sibling. The sibling only exists in the versioned file.
**Example chain:**
1. `openapi.yaml` → `Message.v1_2_1.yaml` (HTTP)
2. `Message.v1_2_1.ya→ `ResolutionStep.yaml` (wrapper)
3. `ResolutionStep.yaml` → `ResolutionStep.v1_0_1.yaml` (versioned)
4. `ResolutionStep.v1_0_1.yaml` has `ResolutionStep_v1_0_1_ResolutionStep` with local `$ref: '#/components/schemas/ResolutionStep_v1_0_1_ResolutionType'`
`bundle()` hoists `ResolutionStep_v1_0_1_ResolutionStep` but fails to resolve its sibling `ResolutionStep_v1_0_1_ResolutionType` because it looks in `ResolutionStep.yaml` (the wrapper) instead of `ResolutionStep.v1_0_1.yaml` (the versioned file).
When `_resolve()` fails with `MissingPointerError`, try resolving the same hash fragment against all other files in the `$refs` registry. This handles the case where a local `$ref` targets a sibling schema that exists in a different file than the one retained in the crawl path.
```typescript
// Before: fail immediately
catch (error) {
if (error instanceof MissingPointerError) {
console.warn(`Skipping unresolvable $ref: ${$refPath}`);
return;
}
}
// After: try other files before giving atch (error) {
if (error instanceof MissingPointerError) {
const hash = url.getHash($refPath);
if (hash) {
const baseFile = url.stripHash($refPath);
for (const filePath of Object.keys($refs._$refs)) {
if (filePath === baseFile) continue;
try {
pointer = $refs._resolve(filePath + hash, pathFromRoot, options);
if (pointer) break;
} catch { /* try next file */ }
}
}
if (!pointer) {
console.warn(`Skipping unresolvable $ref: ${$refPath}`);
return;
}
}
}
```
Additionally, when `inventory$Ref` resolves a `$ref` that chains to a different file, the recursive crawl's path is rebased to the resolved file URL so that subsequent local `$ref`s resolve against the correct file.
Tested against the full DMTF Redfish OpenAPI specification (~2600 schemas, ~2670 paths, hundreds of external HTTP files):
- **Before:** 37 "Skipping unresolvable $ref" warnings, 35 schemas lost
- **After:** 0 warnings, all schemas correctly hoisted
- `packages/json-schema-ref-parser/src/bundle.ts` — two changes in `inventory$Ref`:
1. Fallback resolution against all `$refs` files when `MissingPointerError` occurs
2. Crawl path rebase when resolution chains to a different file
Fixes #3412
Signed-off-by: Jason Westover <jwestover@nvidia.com>