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

[aqeelat]

Bug

In packages/shared/src/openApi/3.1.x/parser/index.ts:98, schema $ref pointers are constructed with string interpolation:

const $ref = `#/components/schemas/${name}`;

This does not escape / or ~ per RFC 6901 (JSON Pointer). Schema names containing these characters produce incorrect pointers.

Example: A schema named node/type~special generates #/components/schemas/node/type~special, which decodes to 4 segments ["components", "schemas", "node", "type~special"] instead of the correct 3 segments ["components", "schemas", "node/type~special"].

Suggested Fix

Use the existing pathToJsonPointer utility from packages/shared/src/utils/ref.ts:

import { pathToJsonPointer from "../../../utils/ref";
// ...
const $ref = pathToJsonPointer(["components", "schemas", name]);

This encodes ~ → ~0 and / → ~1, producing #/components/schemas/node~1type~0special.

Affected Files

• packages/shared/src/openApi/3.1.x/parser/index.ts:98 — primary fix
• packages/shared/src/openApi/3.0.x/parser/index.ts — same pattern
• packages/shared/src/openApi/2.0.x/parser/schema.ts — same pattern

Severity

Low — schema names with / or ~ are rare in practice, but the fix is trivial and ensures RFC 6901 compliance.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}

[mrlubos]

@aqeelat are you planning to open a pull request for this?

[aqeelat]

@mrlubos do you want me to include it in #3889? or in a separate PR?

[mrlubos]

@aqeelat separate please