feat: upgrade to Zod v4 #1030
Draft
feat: upgrade to Zod v4 #1030
+643
−760
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Automated transformations applied via zod-v3-to-v4:
- String validators: z.string().url() → z.url()
- Number validators: z.number().int() → z.int()
- Object methods: .passthrough() → z.looseObject(), .strict() → z.strictObject()
- Schema composition: .merge() → .extend() where applicable
- Error messages: { message } → { error }
- Defaults: .default() → .prefault()
- Object stripping: .strip() removed/consolidated
Remove the external zod-to-json-schema library in preparation for migrating to Zod v4's native toJSONSchema() method.
Replace zodToJsonSchema() calls with Zod v4's native z.toJSONSchema() method. Use default options (JSON Schema Draft 2020-12) for simplicity and standard compliance. Removed unnecessary options: - target: 'openapi-3.0' - default draft-2020-12 is appropriate for MCP - strictUnions: true - option doesn't exist in Zod v4's native implementation
Replace removed/renamed types with v4 equivalents: - AnyZodObject → ZodObject<any> - z.objectOutputType<> → z.infer<ZodObject<>> - Remove ZodTypeDef import (will be addressed with PromptArgsRawShape fix) This resolves 4 compilation errors (Category B & C).
Replace generic ZodType<string, ZodTypeDef, string> with concrete ZodString type. This fixes compatibility with Zod v4's internal type system changes. Resolves 8 compilation errors (Category D & F): - 5 errors in mcp.ts type constraints - 3 cascading errors in example servers
The previous class-based approach that extended ZodType no longer works in Zod v4 due to architectural changes. This implements an immutable wrapper approach that creates a new schema object with completion metadata while preserving all validation behavior. - Creates new schema via Object.create() + property copying - Adds completion metadata to new _def object (not mutating shared state) - Maintains _def === _zod.def invariant - Preserves all schema properties including getters - Follows Zod's immutability pattern Also updates mcp.ts to check _def.typeName instead of instanceof. All 755 tests pass.
Extracts the intersection type to a named CompletableSchema<T> type alias, making the function signature more readable and reusable.
- Remove unused ZodTypeAny import - Replace any with ZodRawShape in RegisteredTool interface - Apply prettier formatting to modified files
felixweinberger
force-pushed
the
fweinberger/zod-v4
branch
from
d0998cb to
d22ef6e
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Upgrades the SDK from Zod v3 to v4 through a systematic, auditable migration process.
Motivation and Context
Zod v4 was released with significant improvements including native JSON Schema support, better type inference, and a more stable API. This upgrade:
zod-to-json-schemalibraryNOTE: last commit is just fixing lint errors - recommend reviewing commits individually.
Key Implementation Detail
The Completable rewrite (commit f46f2ac) deserves special attention. This implements an immutable wrapper pattern that:
_defproperty)_def === _zod.definvariant required by Zod v4How Has This Been Tested?
✅ All 755 tests pass unchanged (no test modifications required)
✅ Build succeeds with 0 errors (down from 29 compilation errors)
✅ Lint passes (eslint + prettier)
✅ True drop-in replacement - full behavioral preservation
Commits are organized for easy review:
Breaking Changes
None.
Types of changes
Checklist
Additional context
Migration path: Since we bundle Zod as a dependency (not peerDependency), users get the upgrade automatically when updating the SDK. No code changes required in user applications.