Skip to content

feat(zod): promote zod4 converter to stable #763

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dinwwwh merged 1 commit into from
Jul 14, 2025
Merged

feat(zod): promote zod4 converter to stable #763

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ This is a quick overview of how to use oRPC. For more details, please refer to t

```ts
import { OpenAPIGenerator } from '@orpc/openapi'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'

const generator = new OpenAPIGenerator({
schemaConverters: [new ZodToJsonSchemaConverter()]
Expand Down
4 changes: 1 addition & 3 deletions apps/content/docs/openapi/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,9 +171,7 @@ Just a small tweak makes your oRPC API OpenAPI-compliant!

```ts twoslash
import { OpenAPIGenerator } from '@orpc/openapi'
import {
experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter
} from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { router } from './shared/planet'

const generator = new OpenAPIGenerator({
Expand Down
2 changes: 1 addition & 1 deletion apps/content/docs/openapi/openapi-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ import {
ZodToJsonSchemaConverter
} from '@orpc/zod' // <-- zod v3
import {
experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter
ZodToJsonSchemaConverter
} from '@orpc/zod/zod4' // <-- zod v4
Comment on lines +75 to 76
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

To avoid naming conflicts, rename the imported ZodToJsonSchemaConverter from @orpc/zod/zod4 to ZodToJsonSchemaConverterV4.

Suggested change
ZodToJsonSchemaConverter
} from '@orpc/zod/zod4' // <-- zod v4
import {
ZodToJsonSchemaConverter as ZodToJsonSchemaConverterV4
} from '@orpc/zod/zod4' // <-- zod v4

import {
experimental_ValibotToJsonSchemaConverter as ValibotToJsonSchemaConverter
Expand Down
4 changes: 1 addition & 3 deletions apps/content/docs/openapi/plugins/openapi-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,7 @@ This plugin relies on the [OpenAPI Generator](/docs/openapi/openapi-specificatio
## Setup

```ts
import {
experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter
} from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'

const handler = new OpenAPIHandler(router, {
Expand Down
2 changes: 1 addition & 1 deletion packages/json-schema/src/smart-coercion-plugin.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import * as z from 'zod'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '../../zod/src/zod4'
import { ZodToJsonSchemaConverter } from '../../zod/src/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from './smart-coercion-plugin'

describe('smartCoercionPlugin', () => {
Expand Down
2 changes: 1 addition & 1 deletion packages/openapi/src/openapi-generator.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import type { AnyContractProcedure } from '@orpc/contract'
import { eventIterator, oc } from '@orpc/contract'
import * as z from 'zod'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '../../zod/src/zod4'
import { ZodToJsonSchemaConverter } from '../../zod/src/zod4'
import { customOpenAPIOperation } from './openapi-custom'
import { OpenAPIGenerator } from './openapi-generator'

Expand Down
2 changes: 1 addition & 1 deletion packages/zod/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ const Example = z.object({

```ts
import { OpenAPIGenerator } from '@orpc/openapi'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'

const openAPIGenerator = new OpenAPIGenerator({
schemaConverters: [new ZodToJsonSchemaConverter()],
Expand Down
2 changes: 1 addition & 1 deletion packages/zod/src/zod4/converter.components.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { z } from 'zod/v4'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from './converter'
import { ZodToJsonSchemaConverter } from './converter'

const User = z.object({
id: z.string(),
Expand Down
2 changes: 1 addition & 1 deletion packages/zod/src/zod4/converter.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import * as z from 'zod/v4'
import * as zm from 'zod/v4-mini'
import {
experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter,
ZodToJsonSchemaConverter,
} from './converter'

describe('zodToJsonSchemaConverter', () => {
Expand Down
18 changes: 9 additions & 9 deletions packages/zod/src/zod4/converter.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ import {
experimental_JSON_SCHEMA_REGISTRY as JSON_SCHEMA_REGISTRY,
} from './registries'

export interface experimental_ZodToJsonSchemaConverterOptions {
export interface ZodToJsonSchemaConverterOptions {
/**
* Max depth of lazy type.
Comment on lines +42 to 44
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Public-API rename introduces a breaking change

Renaming experimental_ZodToJsonSchemaConverterOptions ⇒ ZodToJsonSchemaConverterOptions without leaving an alias will break every external consumer still importing the experimental name.

Add a backward-compatibility shim so existing users are not forced into an immediate major-version upgrade:

+/** @deprecated – will be removed in the next major */
+export type experimental_ZodToJsonSchemaConverterOptions =
+  ZodToJsonSchemaConverterOptions
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
export interface ZodToJsonSchemaConverterOptions {
/**
* Max depth of lazy type.
export interface ZodToJsonSchemaConverterOptions {
/**
* Max depth of lazy type.
*/
}
// @deprecated – will be removed in the next major
export type experimental_ZodToJsonSchemaConverterOptions =
ZodToJsonSchemaConverterOptions
🤖 Prompt for AI Agents 
In packages/zod/src/zod4/converter.ts around lines 42 to 44, the interface was
renamed from experimental_ZodToJsonSchemaConverterOptions to
ZodToJsonSchemaConverterOptions, which breaks backward compatibility. To fix
this, add a type alias exporting experimental_ZodToJsonSchemaConverterOptions as
ZodToJsonSchemaConverterOptions so existing consumers can still import the old
name without breaking.

*
Expand Down Expand Up @@ -85,15 +85,15 @@ export interface experimental_ZodToJsonSchemaConverterOptions {
>[]
}

export class experimental_ZodToJsonSchemaConverter implements ConditionalSchemaConverter {
private readonly maxLazyDepth: Exclude<experimental_ZodToJsonSchemaConverterOptions['maxLazyDepth'], undefined>
private readonly maxStructureDepth: Exclude<experimental_ZodToJsonSchemaConverterOptions['maxStructureDepth'], undefined>
private readonly anyJsonSchema: Exclude<experimental_ZodToJsonSchemaConverterOptions['anyJsonSchema'], undefined>
private readonly unsupportedJsonSchema: Exclude<experimental_ZodToJsonSchemaConverterOptions['unsupportedJsonSchema'], undefined>
private readonly undefinedJsonSchema: Exclude<experimental_ZodToJsonSchemaConverterOptions['undefinedJsonSchema'], undefined>
private readonly interceptors: Exclude<experimental_ZodToJsonSchemaConverterOptions['interceptors'], undefined>
export class ZodToJsonSchemaConverter implements ConditionalSchemaConverter {
private readonly maxLazyDepth: Exclude<ZodToJsonSchemaConverterOptions['maxLazyDepth'], undefined>
private readonly maxStructureDepth: Exclude<ZodToJsonSchemaConverterOptions['maxStructureDepth'], undefined>
private readonly anyJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['anyJsonSchema'], undefined>
private readonly unsupportedJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['unsupportedJsonSchema'], undefined>
private readonly undefinedJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['undefinedJsonSchema'], undefined>
private readonly interceptors: Exclude<ZodToJsonSchemaConverterOptions['interceptors'], undefined>

constructor(options: experimental_ZodToJsonSchemaConverterOptions = {}) {
constructor(options: ZodToJsonSchemaConverterOptions = {}) {
Comment on lines +88 to +96
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Jul 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Same breaking change for the class – please keep a deprecated alias

+/** @deprecated – will be removed in the next major */
+export class experimental_ZodToJsonSchemaConverter
+  extends ZodToJsonSchemaConverter {}

This adds zero runtime cost yet preserves compatibility for downstream libraries/tests that still rely on the experimental identifier.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
export class ZodToJsonSchemaConverter implements ConditionalSchemaConverter {
private readonly maxLazyDepth: Exclude<ZodToJsonSchemaConverterOptions['maxLazyDepth'], undefined>
private readonly maxStructureDepth: Exclude<ZodToJsonSchemaConverterOptions['maxStructureDepth'], undefined>
private readonly anyJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['anyJsonSchema'], undefined>
private readonly unsupportedJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['unsupportedJsonSchema'], undefined>
private readonly undefinedJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['undefinedJsonSchema'], undefined>
private readonly interceptors: Exclude<ZodToJsonSchemaConverterOptions['interceptors'], undefined>
constructor(options: experimental_ZodToJsonSchemaConverterOptions = {}) {
constructor(options: ZodToJsonSchemaConverterOptions = {}) {
export class ZodToJsonSchemaConverter implements ConditionalSchemaConverter {
private readonly maxLazyDepth: Exclude<ZodToJsonSchemaConverterOptions['maxLazyDepth'], undefined>
private readonly maxStructureDepth: Exclude<ZodToJsonSchemaConverterOptions['maxStructureDepth'], undefined>
private readonly anyJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['anyJsonSchema'], undefined>
private readonly unsupportedJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['unsupportedJsonSchema'], undefined>
private readonly undefinedJsonSchema: Exclude<ZodToJsonSchemaConverterOptions['undefinedJsonSchema'], undefined>
private readonly interceptors: Exclude<ZodToJsonSchemaConverterOptions['interceptors'], undefined>
constructor(options: ZodToJsonSchemaConverterOptions = {}) {
// …existing constructor body…
}
}
/** @deprecated – will be removed in the next major */
export class experimental_ZodToJsonSchemaConverter extends ZodToJsonSchemaConverter {}
🤖 Prompt for AI Agents 
In packages/zod/src/zod4/converter.ts around lines 88 to 96, the class
ZodToJsonSchemaConverter was renamed or changed, causing a breaking change. To
fix this, add a deprecated alias for the previous class name or identifier that
was used experimentally. This alias should point to the new class without adding
runtime cost, preserving backward compatibility for downstream libraries and
tests that still rely on the old identifier.

this.maxLazyDepth = options.maxLazyDepth ?? 2
this.maxStructureDepth = options.maxStructureDepth ?? 10
this.anyJsonSchema = options.anyJsonSchema ?? {}
Expand Down
2 changes: 1 addition & 1 deletion packages/zod/tests/shared.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import type { AnySchema } from '@orpc/contract'
import type { JSONSchema } from '@orpc/openapi'
import {
experimental_ZodSmartCoercionPlugin as ZodSmartCoercionPlugin,
experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter,
ZodToJsonSchemaConverter,
} from '../src/zod4'

export interface SchemaConverterTestCase {
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/astro/src/pages/api/[...rest].ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import '../../polyfill'
import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { onError } from '@orpc/server'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
import { router } from '../../router'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/contract-first/src/main.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { createServer } from 'node:http'
import { OpenAPIHandler } from '@orpc/openapi/node'
import { onError } from '@orpc/server'
import { RPCHandler } from '@orpc/server/node'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { router } from './router'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/nest/src/reference/reference.service.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { OpenAPIGenerator } from '@orpc/openapi'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { contract } from 'src/contract'
import { CredentialSchema, TokenSchema } from 'src/schemas/auth'
import { NewPlanetSchema, PlanetSchema, UpdatePlanetSchema } from 'src/schemas/planet'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/next/src/app/api/[[...rest]]/route.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { router } from '@/router'
import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { onError } from '@orpc/server'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
import '../../../polyfill'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/nuxt/server/routes/api/[...].ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { OpenAPIHandler } from '@orpc/openapi/node'
import { onError } from '@orpc/server'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { router } from '~/server/router'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/solid-start/src/routes/api/[...rest].ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import type { APIEvent } from '@solidjs/start/server'
import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { router } from '~/router'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { onError } from '@orpc/server'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { router } from '../../../router'
import { onError } from '@orpc/server'
import type { RequestHandler } from '@sveltejs/kit'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
import '../../../polyfill'
Expand Down
2 changes: 1 addition & 1 deletion playgrounds/tanstack-start/src/routes/api/$.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import '~/polyfill'

import { OpenAPIHandler } from '@orpc/openapi/fetch'
import { experimental_ZodToJsonSchemaConverter as ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
import { experimental_SmartCoercionPlugin as SmartCoercionPlugin } from '@orpc/json-schema'
import { createServerFileRoute } from '@tanstack/react-start/server'
import { router } from '~/router/index'
Expand Down