feat(zod): support JSON schema registries (#1695)

Brings the v1 `JSON_SCHEMA_REGISTRY`, `JSON_SCHEMA_INPUT_REGISTRY`, and
`JSON_SCHEMA_OUTPUT_REGISTRY` to `@orpc/zod` v2, so users can customize
the generated JSON schema per Zod schema.

```ts
import { JSON_SCHEMA_REGISTRY } from '@orpc/zod'

const user = z.object({
  name: z.string(),
  age: z.number(),
})

JSON_SCHEMA_REGISTRY.add(user, {
  examples: [{ name: 'John', age: 20 }],
})
```

- Registry entries are merged over the generated schema at any nesting
level; direction-specific registries take precedence over the general
one, matching v1 behavior.
- Registries are typed with `$input`/`$output`, so `examples`,
`default`, etc. are checked against the schema's input/output types.

Author: dinwwwh

packages/json-schema/src/types.ts

@@ -1,7 +1,7 @@
 // eslint-disable-next-line no-restricted-imports
 import type * as Draft2020 from 'json-schema-typed/draft-2020-12'
 
-export type JsonSchema = Draft2020.JSONSchema
+export type JsonSchema<Value = any> = Draft2020.JSONSchema<Value>
 export type JsonSchemaKeywords = typeof Draft2020.keywords[number]
 
 export enum JsonSchemaXNativeType {

packages/zod/package.json

@@ -39,7 +39,8 @@
     "zod": ">=4.3.5"
   },
   "dependencies": {
-    "@orpc/json-schema": "workspace:*"
+    "@orpc/json-schema": "workspace:*",
+    "json-schema-typed": "^8.0.2"
   },
   "devDependencies": {
     "zod": "^4.4.3"

packages/zod/src/converter.test.ts

@@ -2,6 +2,7 @@ import * as v from 'valibot'
 import * as z from 'zod'
 import { $ZodRegistry, toJSONSchema } from 'zod/v4/core'
 import { ZodToJsonSchemaConverter } from './converter'
+import { JSON_SCHEMA_INPUT_REGISTRY, JSON_SCHEMA_OUTPUT_REGISTRY, JSON_SCHEMA_REGISTRY } from './registries'
 
 vi.mock('zod/v4/core', async (original) => {
   const mod = await original<typeof import('zod/v4/core')>()
@@ -227,4 +228,62 @@ describe('zodToJsonSchemaConverter', () => {
       expect(converter.convert(schema, 'input')).toEqual([jsonSchema, false])
     })
   })
+
+  describe('custom json schema registries', () => {
+    it('merges JSON_SCHEMA_REGISTRY entries over the generated schema for both directions', () => {
+      const schema = z.string().min(3)
+      JSON_SCHEMA_REGISTRY.add(schema, { examples: ['example'], minLength: 5 })
+
+      expect(converter.convert(schema, 'input')).toEqual([{
+        type: 'string',
+        minLength: 5,
+        examples: ['example'],
+      }, false])
+
+      expect(converter.convert(schema, 'output')).toEqual([{
+        type: 'string',
+        minLength: 5,
+        examples: ['example'],
+      }, false])
+    })
+
+    it('prefers direction-specific registries over JSON_SCHEMA_REGISTRY', () => {
+      const schema = z.codec(z.string(), z.number(), {
+        decode: value => Number(value),
+        encode: value => String(value),
+      })
+
+      JSON_SCHEMA_REGISTRY.add(schema, { description: 'general' })
+      JSON_SCHEMA_INPUT_REGISTRY.add(schema, { examples: ['20'] })
+      JSON_SCHEMA_OUTPUT_REGISTRY.add(schema, { examples: [20] })
+
+      expect(converter.convert(schema, 'input')).toEqual([{
+        type: 'string',
+        examples: ['20'],
+      }, false])
+
+      expect(converter.convert(schema, 'output')).toEqual([{
+        type: 'number',
+        examples: [20],
+      }, false])
+    })
+
+    it('applies to nested schemas', () => {
+      const name = z.string()
+      JSON_SCHEMA_REGISTRY.add(name, { description: 'name field' })
+
+      const schema = z.object({ name })
+
+      expect(converter.convert(schema, 'input')).toEqual([{
+        type: 'object',
+        properties: {
+          name: {
+            type: 'string',
+            description: 'name field',
+          },
+        },
+        required: ['name'],
+      }, false])
+    })
+  })
 })

packages/zod/src/converter.ts

@@ -2,6 +2,7 @@ import type { AnySchema, JsonSchema, JsonSchemaConverter, JsonSchemaConverterDir
 import type { $ZodType, ToJSONSchemaParams, JSONSchema as ZodJsonSchema } from 'zod/v4/core'
 import { encodeJsonPointerSegment, JsonSchemaFormat, JsonSchemaXNativeType } from '@orpc/json-schema'
 import { globalRegistry, toJSONSchema } from 'zod/v4/core'
+import { JSON_SCHEMA_INPUT_REGISTRY, JSON_SCHEMA_OUTPUT_REGISTRY, JSON_SCHEMA_REGISTRY } from './registries'
 
 export interface ZodToJsonSchemaConverterOptions extends Omit<ToJSONSchemaParams, 'target' | 'io'> {}
 
@@ -68,6 +69,12 @@ export class ZodToJsonSchemaConverter implements JsonSchemaConverter {
           ctx.jsonSchema['x-native-type'] = JsonSchemaXNativeType.Map
         }
 
+        const customJsonSchema = this.getCustomJsonSchema(ctx.zodSchema, direction)
+
+        if (customJsonSchema) {
+          Object.assign(ctx.jsonSchema, customJsonSchema)
+        }
+
         this.options.override?.(ctx)
       },
     })
@@ -99,4 +106,18 @@ export class ZodToJsonSchemaConverter implements JsonSchemaConverter {
 
     return rest
   }
+
+  private getCustomJsonSchema(schema: $ZodType, direction: JsonSchemaConverterDirection): Exclude<JsonSchema, boolean> | undefined {
+    if (direction === 'input' && JSON_SCHEMA_INPUT_REGISTRY.has(schema)) {
+      return JSON_SCHEMA_INPUT_REGISTRY.get(schema) as Exclude<JsonSchema, boolean> | undefined
+    }
+
+    if (direction === 'output' && JSON_SCHEMA_OUTPUT_REGISTRY.has(schema)) {
+      return JSON_SCHEMA_OUTPUT_REGISTRY.get(schema) as Exclude<JsonSchema, boolean> | undefined
+    }
+
+    if (JSON_SCHEMA_REGISTRY.has(schema)) {
+      return JSON_SCHEMA_REGISTRY.get(schema) as Exclude<JsonSchema, boolean> | undefined
+    }
+  }
 }

packages/zod/src/index.ts

@@ -1 +1,2 @@
 export * from './converter'
+export * from './registries'

packages/zod/src/registries.test-d.ts

@@ -0,0 +1,45 @@
+import * as z from 'zod'
+import { JSON_SCHEMA_INPUT_REGISTRY, JSON_SCHEMA_OUTPUT_REGISTRY, JSON_SCHEMA_REGISTRY } from './registries'
+
+const user = z.object({
+  name: z.string(),
+  age: z.string().transform(v => Number(v)),
+})
+
+describe('JSON_SCHEMA_REGISTRY', () => {
+  it('accepts both input and output shapes', () => {
+    JSON_SCHEMA_REGISTRY.add(user, { examples: [{ name: 'John', age: '20' }] })
+    JSON_SCHEMA_REGISTRY.add(user, { examples: [{ name: 'John', age: 20 }] })
+    JSON_SCHEMA_REGISTRY.add(user, { default: { name: 'John', age: '20' } })
+    JSON_SCHEMA_REGISTRY.add(user, { default: { name: 'John', age: 20 } })
+
+    // @ts-expect-error --- age must match input or output type
+    JSON_SCHEMA_REGISTRY.add(user, { examples: [{ name: 'John', age: true }] })
+    // @ts-expect-error --- age is required
+    JSON_SCHEMA_REGISTRY.add(user, { default: { name: 'John' } })
+  })
+})
+
+describe('JSON_SCHEMA_INPUT_REGISTRY', () => {
+  it('only accepts input shapes', () => {
+    JSON_SCHEMA_INPUT_REGISTRY.add(user, { examples: [{ name: 'John', age: '20' }] })
+    JSON_SCHEMA_INPUT_REGISTRY.add(user, { default: { name: 'John', age: '20' } })
+
+    // @ts-expect-error --- age must be the input type (string)
+    JSON_SCHEMA_INPUT_REGISTRY.add(user, { examples: [{ name: 'John', age: 20 }] })
+    // @ts-expect-error --- age must be the input type (string)
+    JSON_SCHEMA_INPUT_REGISTRY.add(user, { default: { name: 'John', age: 20 } })
+  })
+})
+
+describe('JSON_SCHEMA_OUTPUT_REGISTRY', () => {
+  it('only accepts output shapes', () => {
+    JSON_SCHEMA_OUTPUT_REGISTRY.add(user, { examples: [{ name: 'John', age: 20 }] })
+    JSON_SCHEMA_OUTPUT_REGISTRY.add(user, { default: { name: 'John', age: 20 } })
+
+    // @ts-expect-error --- age must be the output type (number)
+    JSON_SCHEMA_OUTPUT_REGISTRY.add(user, { examples: [{ name: 'John', age: '20' }] })
+    // @ts-expect-error --- age must be the output type (number)
+    JSON_SCHEMA_OUTPUT_REGISTRY.add(user, { default: { name: 'John', age: '20' } })
+  })
+})

packages/zod/src/registries.ts

@@ -0,0 +1,60 @@
+import type { JsonSchema } from '@orpc/json-schema'
+import type { $input, $output } from 'zod/v4/core'
+import { registry } from 'zod/v4/core'
+
+/**
+ * Zod registry for customizing generated JSON schema, can use both for .input and .output
+ *
+ * @example
+ * ```ts
+ * import { JSON_SCHEMA_REGISTRY } from '@orpc/zod'
+ *
+ * const user = z.object({
+ *   name: z.string(),
+ *   age: z.number(),
+ * })
+ *
+ * JSON_SCHEMA_REGISTRY.add(user, {
+ *   examples: [{ name: 'John', age: 20 }],
+ * })
+ * ```
+ */
+export const JSON_SCHEMA_REGISTRY = registry<Exclude<JsonSchema<$input | $output>, boolean>>()
+
+/**
+ * Zod registry for customizing generated JSON schema, only useful for .input
+ *
+ * @example
+ * ```ts
+ * import { JSON_SCHEMA_INPUT_REGISTRY } from '@orpc/zod'
+ *
+ * const user = z.object({
+ *   name: z.string(),
+ *   age: z.string().transform(v => Number(v)),
+ * })
+ *
+ * JSON_SCHEMA_INPUT_REGISTRY.add(user, {
+ *   examples: [{ name: 'John', age: "20" }],
+ * })
+ * ```
+ */
+export const JSON_SCHEMA_INPUT_REGISTRY = registry<Exclude<JsonSchema<$input>, boolean>>()
+
+/**
+ * Zod registry for customizing generated JSON schema, only useful for .output
+ *
+ * @example
+ * ```ts
+ * import { JSON_SCHEMA_OUTPUT_REGISTRY } from '@orpc/zod'
+ *
+ * const user = z.object({
+ *   name: z.string(),
+ *   age: z.string().transform(v => Number(v)),
+ * })
+ *
+ * JSON_SCHEMA_OUTPUT_REGISTRY.add(user, {
+ *   examples: [{ name: 'John', age: 20 }],
+ * })
+ * ```
+ */
+export const JSON_SCHEMA_OUTPUT_REGISTRY = registry<Exclude<JsonSchema<$output>, boolean>>()