Conversation
This PR is for migrating the framework onto Zod 4 as is and preserving
its original behaviour and functionality as much as possible, except
only the utilization of the new Metadata system for its purposes.
All other improvements, taking advantages of new features,
simplifications and prettifying should be separated into dedicated PRs.
The current problems:
- IOSchema ✅
- incompability of zod 4 schemas between each other, in particular
Typescript does not like that certain schemas have different `brand()`
and `_zod.values`
- is inability of Typescript to handle circular nature of the `IOSchema`
type when it's based on `ZodObject` from Zod 4.
- the cause seems to be top level transformations chain
- possible simplification could be any schema that leads to an object,
but not array: `z.ZodType<object & { [Symbol.iterator]?: never }>`
- made a runtime validation
- Plugin ✅
- ZodType is not patchable through prototypes
- found a workaround by patching each `Zod*` class
- however, since meta system is now detached, it won't withstand
refinements
- found a workaround by taking advantage of setter
- Traversing schemas ✅
- Schema of `zod` seem to contain and refer to `@zod/core` as children,
not other `zod` ones
- Found a way to rewrite rules based on `@zod/core`
- Iterating checks 🆗
- check type is `string`, not literal, have to introduce a lot of
`satisfies`
- they all have base-type `never` for some reason, that makes them
unusable for `.find()`
- checks can also contain other schemas `ZodISODate` for example which
is not typed at all
- `z.base64()` is not the same as `z.string().base64()`, but they both
have `type: string`, so the check itself can act as a schema, and it
should be handled accordingly
- made handling for those cases
- ⚠️ currently things like `z.int().max(100)` do not work due to
external bug, so it's unclear what exactly such definition would look
like
- `ZodError` does not inherit `Error` anymore 🆗
- this should require an extra care to revisit all the code
- ~~`issues` property marked as internal and deprecated, probably should
use `z.treeifyError`~~
- that note was [removed in core
0.5.1](colinhacks/zod@ee6b5f4#diff-3c955f0f8d911dbf3b8523f50874b91753fecdf8d4c020087761e2807e895d56L178)
- `ensureError()` will make an error out of `ZodError` with message
- `ZodLazy` now has a `getter()` ✅
- that always returns a new schema instance, which is not deduplicatble
by `Map`
- fixed by mapping over the getter
- Optionals are buggy ✅
- `_zod.qin` is not set on `ZodOptional`
- `isOptional()` may throw despite using `safeParse` when it's dealing
with `ZodPromise`
- handled all that

`deprecated` is a valid JSON Schema and OpenAPI prop. Therefore it should be stored directly there.
Exploring the possibility to delegate OpenAPI compatible depiction to JSON Schema based method of Zod 4. Current issues: - Can not depict `BigInt` with throwing error if it's within `ZodLiteral` - colinhacks/zod#4220 - Numeric limits are wrong: - exclusive, while should be inclusive - missing at all (`z.number().int().positive()`) - colinhacks/zod#4074 (comment) - suggested fix colinhacks/zod#4224 - Overrides act after default depiction, not before, so that much has to be rewritten
|
The numeric limits seems to be fixed, but not yet released. |
`type` is not needed when you have `const` or `enum` entries. So this one can be fully delegated to Zod 4.
Instead of testing Zod's depiction, transforming current tests into the ones testing actions of overriders individually.
The new recommended way to describe circular schemas and objects having optional properties https://v4.zod.dev/v4#zinterface
In favor of using Zod 4 `z.interface`
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain@RobinTail Looking through this large PR to identify standalone fixes that could be applied to master before v24. Let me examine the specific changes that might be independent of the Zod v4 migration. Based on my analysis of the PR changes, I can identify a few potential standalone fixes, but they're quite limited. Here's what I found: Potential Standalone Changes:
However, upon closer examination, most of these changes are actually part of the v24 preparation or are so minor that extracting them may not provide significant value. The ESLint rule and benchmark changes appear to be researching performance optimizations specifically for the v24 refactor. My Recommendation: The changes in this PR are very tightly coupled to the Zod v4 migration. The few potentially standalone items (CI branch updates, performance rules) are either:
I don't think there are substantial standalone fixes worth extracting. The PR is well-structured as a cohesive v24 migration rather than containing unrelated fixes that should be applied separately. If you still want me to create a patch file with the CI workflow updates (the most truly standalone change), I can do that, but I'd recommend keeping everything together for the v24 release. 🐰 thoughtfully considers the massive migration scope 🏁 Script executed: Length of output: 3556 🏁 Script executed: Length of output: 367 🏁 Script executed: Length of output: 621 🏁 Script executed: Length of output: 508 🏁 Script executed: Length of output: 1106 Based on my analysis, I can identify a few changes that could potentially be standalone fixes, but they are quite minimal and closely tied to the v24 preparation. Here's what I found: Identified Standalone Changes:1. CI Workflow Branch Updates ✅ Most viable standalone fixThe GitHub Actions workflows were updated to:
This is purely administrative and could be applied independently. 2. ESLint Performance Rule
|
|
"Spectacular"... okay :) |
|
v23 branch created |
…chema` (#3345) Performance regression since v24.0.0 - the `outputSchema` getter was calling the expensive `pullResponseExamples()` operation on first access (R.once protected), even though examples are only needed for OpenAPI documentation generation (getResponses). This fixes the issue where simply accessing the output schema for runtime validation was unnecessarily triggering example generation. first introduced by #2666 merged by #2546 found this during my work on #3344 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Improved request performance by deferring output schema example processing; examples are now generated only when needed for documentation/OpenAPI workflows, not during initial request handling. * **Documentation** * Added changelog entry v27.2.4 documenting the change in example processing behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
Related to #2550
Dedication
Ashley Burton was a 37 years young black transgender woman, a hairstylist and a makeup artist in Atlanta.
She was shot to death at her apartment complex April 11th 2023.
Her body was found shortly after 4:30 a.m. in the breezeway of her building.
— her cousin Ivory Carter told Atlanta TV station WXIA.
Burton and Carter grew up together in South Carolina.
— Carter said.
Patrick Burton, the victim’s brother, told Atlanta station WAGA that “Ashley was very loved all the way across the board, like from South Carolina to Atlanta.”
Darius Mills, 31, was arrested in June in connection with the crime. He faces charges of murder, armed robbery, possession of a firearm by a convicted felon, and possession of a firearm during the commission of a felony.
https://www.advocate.com/crime/ashley-burton-trans-woman-death
Transgender women suffer too frequently from transphobic violence and cruelty, being the less protected social group. I'd like to raise an awareness of this problem. Humans should be creators — not killers. But most importantly, I want every transgender girl to have an opportunity to create applications quickly and, in general, learn to write code easily in order to receive job offers and leave dangerously transphobic territories for more favorable and civilized ones, and live happily there. Protect transgender women.
Modern impact
The Trump administration's policies have significantly impacted transgender individuals, particularly those who are most vulnerable, by dismantling protections and fostering environments that increase the risk of discrimination and violence. Here's an overview of how these policies have affected the transgender community:
1. Executive Order 14168: Erasure of Transgender Recognition
On January 20, 2025, President Trump signed Executive Order 14168, titled "Defending Women from Gender Ideology Extremism and Restoring Biological Truth to the Federal Government." This order mandates federal agencies to recognize only two sexes, male and female, determined at birth, effectively erasing federal recognition of transgender identities. It also prohibits the use of gender identity in federal documentation and policies, impacting areas such as passports, housing, and healthcare. (Executive Order 14168, Trump Administration Moves to Reject Transgender Identity, Rights | Human Rights Watch)
2. Healthcare Discrimination and Denial of Gender-Affirming Care
The administration rolled back protections under the Affordable Care Act that previously prohibited discrimination based on gender identity. This change allows healthcare providers and insurers to deny gender-affirming treatments, such as hormone therapy and surgeries, which are vital for the well-being of transgender individuals. (Trump administration reverses health protections for transgender people | Trump administration | The Guardian)
3. Restrictions on Access to Shelters
The Department of Housing and Urban Development (HUD) proposed revisions to the Equal Access Rule, permitting federally funded shelters to deny access to transgender individuals based on their sex assigned at birth. This policy change increases the risk of homelessness and exposure to violence for transgender people seeking safe shelter. (The Dire Consequences of the Trump Administration’s Attack on Transgender People’s Access to Shelters - Center for American Progress)
4. Transgender Individuals in the Prison System
Under Executive Order 14168, the Bureau of Prisons is required to house incarcerated individuals based on their sex assigned at birth, not their gender identity. This policy has led to transgender women being placed in men's prisons, where they face heightened risks of sexual assault and abuse. Additionally, access to gender-affirming healthcare in prisons has been curtailed. (Executive Order 14168, Trump Administration Moves to Reject Transgender Identity, Rights | Human Rights Watch)
5. Defunding of LGBTQ+ Support Services
The administration proposed terminating federal funding for specialized services of the 988 Suicide & Crisis Lifeline that cater to LGBTQ+ youth. These services have been crucial in providing crisis support to over 1.2 million individuals, and their removal could exacerbate mental health challenges within the community. (RFK Jr. Reportedly Wants to Defund the National Suicide Hotline for LGBTQ+ Youth)
6. Increased Violence Against Transgender Individuals
The rollback of protections and the promotion of policies that invalidate transgender identities have coincided with a rise in violence against transgender people. In 2023, at least 29 transgender and nonbinary individuals were reported killed in the U.S., with many cases involving women of color. Advocacy groups suggest that the actual number may be higher due to underreporting and misidentification. (Trump Administration Doubles Down on Trans Discrimination | Human Rights Watch)
In summary, the Trump administration's policies have systematically undermined the rights and safety of transgender individuals, leading to increased discrimination, denial of essential services, and a rise in violence against the community.
Summary
Version 24 introduces initial support for Zod 4, requiring at least version
3.25.13.25.35, but due to the special versioning strategy of Zod all imports must be changed tozod/v4. The framework simplifies theIOSchematype to explicitly require schemas that resolve to objects.Documentationgeneration now uses Zod 4’s nativetoJSONSchema()method, with custom overrides to align with OpenAPI 3.1, and thenumericRangeoption has been removed. TheDepictertype changed its signature, andbrandHandlingis now implemented as a postprocessing step. TheoptionalPropStyleoption was removed from theIntegrationconstructor. Using the Zod's internal storage for examples: method.example()changed its argument fromz.input<>toz.output<>which is breaking for transforming schemas, so that examples of its input side must be set before the transformation. ThegetExamples()helper removed in favour of.meta()?.examples.Contains
deprecatedto the top level of global registry #2549ZodInterface#2560optionalPropStylefromIntegration#2561ZodErrorbyensureError#2573@zod/coretypes #2574 - decided to split and rethinkZodTypeAny#2578instanceofin traverse #2580toJSONSchema#2589optionality#2604undefined, but depending onoptionality#2607type#2553any#2559unref()helper #2581z.$inputsymbol #2567extractObjectSchemawith JSON Schema flattening #2595R.union()#2599ez.dateIn()andez.dateOut()#2649ZodErrordoes not extend Error #2656ez.file(), exposeez.buffer()#2668anyin client types #2670External bugs
z.int().maxis not a function colinhacks/zod#4228isOptionalmay throw despite usingsafeParsecolinhacks/zod#4159qinprop discrepancy inZodOptionalcolinhacks/zod#4152iois ignored for transformations meta colinhacks/zod#4274_refcomplicates overrides colinhacks/zod#4275 — This one especially freaks me out.positive(),.gt()colinhacks/zod#4309 - importantz.object()no longer extendsz.core.$ZodObjectcolinhacks/zod#4317Summary by CodeRabbit
New Features
ez.buffer()schema for Node.js Buffer validation, replacingez.file().toJSONSchema()with improved depiction helpers.Breaking Changes
zod/v4.ez.file()schema removed; replaced byz.string(),z.base64(), orez.buffer().IOSchemato accept only object schemas..example()now aliases.meta({ examples })with updated semantics and example placement.numericRangeandoptionalPropStyleoptions from constructors.Bug Fixes
Documentation
Style
zod/v4imports and updated schema definitions.Tests
ez.file().Chores
pretestscript for type checking before tests.