What are the advantages of .extend()? Are there any?

[Svish]

Going through the migration guide and eventually found myself reading about .extend() and the alternative spread syntax. It lists some advantages of using the spread syntax, but no disadvantages or advantages of using .extend().

Are there any advantages of using .extend()? If the spread syntax is better and more efficient in every way, is there a reason to use it at all? Should it basically just be mared as deprecated?

[dosubot[bot]]

There are still good reasons to use .extend() in Zod, and it is not deprecated. While the migration guide highlights that spread syntax (object destructuring) is more TypeScript-compiler efficient—especially for large schemas or deeply chained extensions—.extend() remains a core, supported API with its own advantages.

.extend() is recommended over intersections when merging object schemas because it returns a new object schema that supports methods like .pick and .omit, which intersections do not. It also provides a clear, readable way to add or overwrite fields on an existing schema, and is used throughout the docs and examples, including for discriminated unions and schema composition. In Zod 4, .extend() and related methods have been optimized for much better TypeScript performance compared to Zod 3, so chaining them is now much more efficient than before (docs, changelog).

Spread syntax is preferred if you want maximum TypeScript performance or need to control the strictness level of the resulting schema at a glance. But .extend() is still idiomatic, supported, and useful—especially when you want to chain schema methods or rely on Zod’s object schema API.

Let me know if this answers your question—if so, feel free to close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Svish]

Well that was long non-answer with still no actual advantages of .extend() listed...

[dosubot[bot]]

Here are the concrete advantages of using .extend() in Zod:

• It returns a new Zod object schema, so you can keep chaining Zod methods like .pick(), .omit(), .partial(), etc. This is not possible if you use intersections (z.intersection()), which return a ZodIntersection instance that lacks these methods (docs).
• It's the recommended way to merge object schemas in Zod, especially after .merge() was deprecated. .extend() avoids ambiguity around strictness inheritance and has better TypeScript performance than .merge() (changelog).
• It's idiomatic and used throughout the docs and examples, including for discriminated unions and schema composition. For example, extending a base error schema for different error codes in a discriminated union (docs).
• In Zod 4, chaining .extend() and .omit() is much more TypeScript-compiler efficient than in Zod 3, so it's practical for large schemas and complex chains (docs).
• .extend() provides a clear, readable way to add or overwrite fields on an existing schema, which can be safer and more explicit than manually spreading shapes.

Spread syntax is great for TypeScript performance and strictness control, but .extend() is still fully supported, not deprecated, and remains the best choice when you want to keep using Zod's object schema API.

Let me know if this answers your question—if so, feel free to close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Svish]

None of these are concrete advantages of using .extend().

• So does using spread syntax
• No it isn't, the docs specifically says spread syntax is faster and better than .extend().
• It was idiomatic in v3, but that doesn't mean it should be in v4
• But the v4 docs claim spread syntax is even more TS-compiler efficient than extend
• Using .extend() does not make it any more or less explicit than spread syntax

Fully supported and not deprecated is not an argument for why it would be the "best choice" when the current docs even says spread syntax is better.

You're not answering any of my questions.

[dosubot[bot]]

You're right—the Zod v4 docs and recent updates explicitly recommend spread syntax over .extend() for extending schemas, mainly because spread syntax is more TypeScript-compiler efficient (especially for large schemas or deep chains), uses language-level features, and gives you explicit control over strictness with z.object, z.strictObject, or z.looseObject (docs, changelog, PR #4919).

There are no unique technical advantages to .extend() over spread syntax in Zod 4 for most use cases. Both approaches let you chain Zod methods and produce a Zod object schema. .extend() is still fully supported and used in examples (like discriminated unions), but it's not more explicit, safer, or more efficient than spread syntax. The only edge case where .extend() (or the new .safeExtend()) might be preferable is if you want to programmatically extend an existing schema object in a way that fits a fluent API style, or if you want to avoid manual shape spreading in dynamic scenarios. But for static schema composition, spread syntax is the recommended and more efficient approach.

Let me know if you want more details or examples from the docs!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Svish]

Thanks for nothing. Go die in a ditch, AI bot.