fix: toJsonSchema definition key with / or ~ not encoded in $ref (#1482)

* fix: `toJsonSchema` definition key with `/` or `~` not encoded as JSON Pointer in `$ref`

Fixes #1481

* Update changelog with fix for $ref generation

---------

Co-authored-by: Fabian Hiller <hillerfabian11@gmail.com>

Author: dinwwwh

packages/to-json-schema/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to the library will be documented in this file.
 
+## vX.X.X (Month DD, YYYY)
+
+- Fix `$ref` generation to encode definition keys containing `/` or `~` as JSON Pointer tokens (pull request #1482)
+
 ## v1.7.0 (May 05, 2026)
 
 - Change build target to ES2020 so distributed output stays compatible with environments that lack support for newer syntax (pull request #1455)

packages/to-json-schema/src/converters/convertSchema/convertSchema.test.ts

@@ -24,6 +24,23 @@ describe('convertSchema', () => {
       });
     });
 
+    test('should encode definition key as JSON Pointer in reference', () => {
+      const schema = v.string();
+      expect(
+        convertSchema(
+          {},
+          schema,
+          undefined,
+          createContext({
+            definitions: { 'Shared/User~': { type: 'string' } },
+            referenceMap: new Map().set(schema, 'Shared/User~'),
+          })
+        )
+      ).toStrictEqual({
+        $ref: '#/$defs/Shared~1User~0',
+      });
+    });
+
     test('should skip definition if specified', () => {
       const stringSchema = v.string();
       expect(

packages/to-json-schema/src/converters/convertSchema/convertSchema.ts

@@ -123,6 +123,17 @@ function flattenPipe(pipe: Pipe): Pipe {
   );
 }
 
+/**
+ * Returns the JSON Pointer reference for a definition key.
+ *
+ * @param referenceId The unescaped definition key.
+ *
+ * @returns The encoded JSON Pointer fragment.
+ */
+function getDefinitionRef(referenceId: string): string {
+  return `#/$defs/${referenceId.replaceAll('~', '~0').replaceAll('/', '~1')}`;
+}
+
 // Create global reference count
 let refCount = 0;
 
@@ -148,7 +159,7 @@ export function convertSchema(
     // If schema is in reference map use reference and skip conversion
     const referenceId = context.referenceMap.get(valibotSchema);
     if (referenceId) {
-      jsonSchema.$ref = `#/$defs/${referenceId}`;
+      jsonSchema.$ref = getDefinitionRef(referenceId);
       if (config?.overrideRef) {
         const refOverride = config.overrideRef({
           ...context,
@@ -631,7 +642,7 @@ export function convertSchema(
       }
 
       // Add reference to JSON Schema object
-      jsonSchema.$ref = `#/$defs/${referenceId}`;
+      jsonSchema.$ref = getDefinitionRef(referenceId);
 
       // Override reference, if necessary
       if (config?.overrideRef) {

packages/to-json-schema/src/functions/toJsonSchema/toJsonSchema.test.ts

@@ -139,6 +139,31 @@ describe('toJsonSchema', () => {
         },
       });
     });
+
+    test('for definitions with JSON Pointer special characters', () => {
+      const sharedSchema = v.object({ name: v.string() });
+      expect(
+        toJsonSchema(v.object({ user: sharedSchema }), {
+          definitions: { 'Shared/User~': sharedSchema },
+        })
+      ).toStrictEqual({
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        type: 'object',
+        properties: {
+          user: { $ref: '#/$defs/Shared~1User~0' },
+        },
+        required: ['user'],
+        $defs: {
+          'Shared/User~': {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+            },
+            required: ['name'],
+          },
+        },
+      });
+    });
   });
 
   describe('should throw error', () => {