feat(zod): promote zod4 converter to stable#763
Conversation
WalkthroughAll references to the experimental Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant App/Docs/Test
participant ZodToJsonSchemaConverter
User->>App/Docs/Test: Import ZodToJsonSchemaConverter
App/Docs/Test->>ZodToJsonSchemaConverter: Instantiate/use converter
ZodToJsonSchemaConverter-->>App/Docs/Test: Convert Zod schema to JSON Schema
App/Docs/Test-->>User: Return or document JSON Schema
Possibly related PRs
Suggested labels
Poem
✨ Finishing Touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
dosubot
Bot
added
the
size:M
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @unnoq, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request officially stabilizes the Zod v4 JSON schema converter by removing its experimental_ prefix. This change signifies that the converter is now considered production-ready, and all relevant code, documentation, and examples have been updated to reflect this new stable status, ensuring users can confidently integrate it into their projects.
Highlights
- API Stabilization: The
ZodToJsonSchemaConverterfor Zod v4 has been promoted from an experimental status to stable. This indicates that the converter is now considered production-ready. - Codebase Update: All internal references, documentation, and examples across the repository have been updated to reflect the new stable name,
ZodToJsonSchemaConverter, removing theexperimental_prefix.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
Codecov ReportAll modified and coverable lines are covered by tests ✅ 📢 Thoughts on this report? Let us know! |
| ZodToJsonSchemaConverter | ||
| } from '@orpc/zod/zod4' // <-- zod v4 |
There was a problem hiding this comment.
To avoid naming conflicts, rename the imported ZodToJsonSchemaConverter from @orpc/zod/zod4 to ZodToJsonSchemaConverterV4.
| ZodToJsonSchemaConverter | |
| } from '@orpc/zod/zod4' // <-- zod v4 | |
| import { | |
| ZodToJsonSchemaConverter as ZodToJsonSchemaConverterV4 | |
| } from '@orpc/zod/zod4' // <-- zod v4 |
More templates
@orpc/arktype
@orpc/client
@orpc/contract
@orpc/experimental-durable-event-iterator
@orpc/hey-api
@orpc/json-schema
@orpc/nest
@orpc/openapi
@orpc/openapi-client
@orpc/react
@orpc/react-query
@orpc/server
@orpc/shared
@orpc/solid-query
@orpc/standard-server
@orpc/standard-server-aws-lambda
@orpc/standard-server-fetch
@orpc/standard-server-node
@orpc/standard-server-peer
@orpc/svelte-query
@orpc/tanstack-query
@orpc/trpc
@orpc/valibot
@orpc/vue-colada
@orpc/vue-query
@orpc/zod
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🔭 Outside diff range comments (1)
apps/content/docs/openapi/openapi-specification.md (1)
70-76: Duplicate identifier: the twoZodToJsonSchemaConverterimports will not compileBoth v3 and v4 snippets import the symbol with the exact same name, which causes a
Duplicate identifier 'ZodToJsonSchemaConverter'error in a real TypeScript file.Either (a) show one of the versions, or (b) alias the second one:
-import { - ZodToJsonSchemaConverter -} from '@orpc/zod/zod4' // <-- zod v4 +// Pick ONE of the two versions, or alias the v4 variant if you want both: +import { + ZodToJsonSchemaConverter as ZodToJsonSchemaConverterV4 +} from '@orpc/zod/zod4' // <-- zod v4and adjust the later usage accordingly.
Without this change the example cannot be copy-pasted.
♻️ Duplicate comments (4)
playgrounds/nest/src/reference/reference.service.ts (1)
2-2: Same export-resolution concern as noted insmart-coercion-plugin.test.ts
Please verify the./zod4sub-path export.packages/zod/src/zod4/converter.components.test.ts (1)
2-2: Same export-resolution concern as noted earlier
Validate that@orpc/zod/zod4is an exported entry.playgrounds/astro/src/pages/api/[...rest].ts (1)
4-4: Same export-resolution concern as noted earlier
Ensure@orpc/zodexposes the./zod4path.playgrounds/solid-start/src/routes/api/[...rest].ts (1)
4-4: Same export-resolution concern as noted earlier
Verify@orpc/zod/zod4is declared in the package exports.
🧹 Nitpick comments (3)
packages/openapi/src/openapi-generator.test.ts (1)
4-4: Prefer package alias over brittle relative pathImporting from
"../../zod/src/zod4"ties the test to the folder layout and bypasses the package entrypoints.
@orpc/zod/zod4is already used elsewhere and would stay valid even if the repo structure shifts.-import { ZodToJsonSchemaConverter } from '../../zod/src/zod4' +import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'playgrounds/nuxt/server/routes/api/[...].ts (1)
3-3: Minor: consider re-using a single converter instanceYou create two separate
new ZodToJsonSchemaConverter()objects (one per plugin).
Unless the plugins mutate converter state, a single shared instance would save tiny allocation time and keep configs in sync.No action required, just a thought.
playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts (1)
5-5: Same remark as in Nuxt route – two independentZodToJsonSchemaConverterinstances are instantiated for different plugins; sharing one could be simpler.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (19)
README.md(1 hunks)apps/content/docs/openapi/getting-started.md(1 hunks)apps/content/docs/openapi/openapi-specification.md(1 hunks)apps/content/docs/openapi/plugins/openapi-reference.md(1 hunks)packages/json-schema/src/smart-coercion-plugin.test.ts(1 hunks)packages/openapi/src/openapi-generator.test.ts(1 hunks)packages/zod/README.md(1 hunks)packages/zod/src/zod4/converter.components.test.ts(1 hunks)packages/zod/src/zod4/converter.test.ts(1 hunks)packages/zod/src/zod4/converter.ts(2 hunks)packages/zod/tests/shared.ts(1 hunks)playgrounds/astro/src/pages/api/[...rest].ts(1 hunks)playgrounds/contract-first/src/main.ts(1 hunks)playgrounds/nest/src/reference/reference.service.ts(1 hunks)playgrounds/next/src/app/api/[[...rest]]/route.ts(1 hunks)playgrounds/nuxt/server/routes/api/[...].ts(1 hunks)playgrounds/solid-start/src/routes/api/[...rest].ts(1 hunks)playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts(1 hunks)playgrounds/tanstack-start/src/routes/api/$.ts(1 hunks)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: publish-commit
- GitHub Check: lint
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (10)
packages/json-schema/src/smart-coercion-plugin.test.ts (1)
2-2: Ensure./zod4sub-path is properly exportedThe new import hinges on
@orpc/zoddeclaring an explicit"./zod4"entry in its"exports"/"types"map; otherwise consumers will getERR_PACKAGE_PATH_NOT_EXPORTED(Node ≥ 16) or resolution failures in bundlers.Confirm that
packages/zod/package.json(and the build artefacts) include this sub-path before publishing.packages/zod/tests/shared.ts (1)
5-5: LGTM – stable converter import looks correct
No further issues spotted.packages/zod/src/zod4/converter.test.ts (1)
4-5: LGTM – import updated to stable name
Everything else in this test remains unaffected.playgrounds/next/src/app/api/[[...rest]]/route.ts (1)
4-4: Clean API stabilization - LGTM!The import update from experimental to stable
ZodToJsonSchemaConverteris well-executed. The usage patterns remain identical, ensuring smooth transition from experimental to stable API.packages/zod/README.md (1)
89-89: Documentation properly updated for stable API - LGTM!The example code correctly demonstrates the stable import path, helping users transition from the experimental API to the stable version.
playgrounds/contract-first/src/main.ts (1)
5-5: Consistent API stabilization across playground - LGTM!The import update maintains consistency with the broader API stabilization effort while preserving all existing functionality.
apps/content/docs/openapi/plugins/openapi-reference.md (1)
17-17: Documentation correctly updated for stable API - LGTM!The setup example now properly demonstrates the stable import, ensuring users follow the correct integration pattern.
playgrounds/tanstack-start/src/routes/api/$.ts (1)
4-4: Final piece of consistent API stabilization - LGTM!The import update completes the cohesive transition from experimental to stable API across all playground examples, maintaining functional consistency.
README.md (1)
178-184: Looks good – import updated to the stable symbolThe example now refers to the promoted
ZodToJsonSchemaConverter; no further action required.apps/content/docs/openapi/getting-started.md (1)
172-180: LGTM – import correctly switched to the stable nameThe snippet is self-contained and compiles as-is.
| export interface ZodToJsonSchemaConverterOptions { | ||
| /** | ||
| * Max depth of lazy type. |
There was a problem hiding this comment.
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.
| 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.
| 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 = {}) { |
There was a problem hiding this comment.
🛠️ 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.
| 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.
1 participant
Summary by CodeRabbit
Documentation
ZodToJsonSchemaConverterinstead of the previous experimental alias. This streamlines and clarifies usage instructions for OpenAPI spec generation.Refactor