fix: incorrect $ref generation for schema names containing / or ~

[aqeelat]

Fix

Replace string interpolation with pathToJsonPointer() when constructing $ref JSON Pointers in OpenAPI parsers. This ensures ~ and / in schema/component names are properly encoded (~0, ~1) per RFC 6901.

Problem

Schema names containing / or ~ produce malformed JSON Pointers. For example, a schema named node/type~special generated #/components/schemas/node/type~special, which decodes to 4 segments instead of the correct 3 segments ["components", "schemas", "node/type~special"].

Changes

• packages/shared/src/openApi/3.1.x/parser/index.ts — 3 interpolations replaced
• packages/shared/src/openApi/3.0.x/parser/index.ts — 3 interpolations replaced
• packages/shared/src/openApi/2.0.x/parser/index.ts — 1 interpolation replaced
• packages/shared/src/utils/__tests__/ref.test.ts — 3 new test cases for RFC 6901 encoding

Fixes #3888

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[vercel]

@aqeelat is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7591338

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

No new issues found in the changed scope.

TL;DR — Routes the four parser-emitted $ref constructions through pathToJsonPointer, restoring RFC 6901 encoding for schema/parameter/requestBody names that contain ~ or /. The fix is correct and matches the encoding already performed by buildGraph.

Key changes

• Encode parser $ref segments — replaces raw `#/components/.../${name}` interpolations in parseV3_1_X, parseV3_0_X, and parseV2_0_X with pathToJsonPointer([...segments, name]).
• Adds RFC 6901 tests — covers ~, /, and combined cases in pathToJsonPointer.

_{Summary ｜ 4 files ｜ 1 commit ｜ base: main ← fix/3888-json-pointer-encoding}

Consistency with the graph layer

Before: parser emitted #/components/schemas/node/type~special (4 decoded segments), while buildGraph keyed the same node as #/components/schemas/node~1type~0special (3 segments) via encodeJsonPointerSegment.
After: both sides agree, so downstream lookups (graph.nodes.get(pointer), resolveRef, jsonPointerToPath) round-trip correctly for schema names containing ~ or /.

The four call sites cover every top-level $ref produced by the parsers themselves: components.parameters, components.requestBodies, components.schemas (3.x) and definitions (2.0). Securitysschemes uses name as a map key, not a $ref, so it stays as is.

parser/index.ts (3.1.x) · parser/index.ts (3.0.x) · parser/index.ts (2.0.x) · ref.test.ts

Out-of-scope follow-up

Note: packages/shared/src/openApi/shared/transforms/readWrite.ts still builds pointer strings via raw interpolation in several places — originals[\#/components/schemas/${name}`], originals[`#/definitions/${name}`], and the ${schemasPointerNamespace}${name}joins insplitSchemas/splitDiscriminatorSchemas`.

For schemas whose names contain ~ or /, those keys won't match graph.nodes (which is already encoded) and the readWrite split can silently leave originals behind or fail to rewrite $refs. The internal lookups in that file are mutually consistent (un-encoded throughout), so existing tests don't catch it. Worth a separate PR — out of scope here.

readWrite.ts

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using Claude Opus ｜ 𝕏}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 38.73%. Comparing base (4951d45) to head (7591338).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3903      +/-   ##
==========================================
+ Coverage   37.73%   38.73%   +1.00%     
==========================================
  Files         582      593      +11     
  Lines       20837    21327     +490     
  Branches     6066     6253     +187     
==========================================
+ Hits         7862     8262     +400     
- Misses      10567    10667     +100     
+ Partials     2408     2398      -10     

Flag	Coverage Δ
unittests	38.73% <100.00%> (+1.00%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3903

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3903

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3903

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3903

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3903

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3903

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3903

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3903

commit: 7591338