Extending built-in validation objects

[cgatian]

Is there anyway to extend the built-in validations like z.string() with my own shared validations?
For example, we have specific validation for shipment indentifiers. I would love if we could, across our entire application just use the following:

z.object({
   shipmentIdentifier: z.shippingId
})

I think the only way to do this is to export the schema as an object:

import { shippingIdSchema } '@lib/shared-schemas';
import { z } from 'zod/v4';

const schema = z.object({
   shipmentIdentifier: shippingIdSchema()
});

I've tried the approaches in this discussion:
#2616

But all fail due to issues overriding the z namespace properly.

[dosubot[bot]]

You can't safely extend the z namespace (e.g., z.shippingId) in Zod due to how it's exported as a frozen ES module object—direct assignment or TypeScript module augmentation won't work reliably and will break in production builds (source, source). This is a technical limitation of how Zod is structured and how ES modules work in JavaScript/TypeScript.

The idiomatic way to share custom validations (like a shipment identifier) is to export your custom schema or helper function and import it wherever needed. For example:

// shared-schemas.ts
import { z } from "zod";
export const shippingIdSchema = () =>
  z.string().regex(/^SHIP-\d{6}$/, { message: "Invalid shipment ID" });

// usage
import { shippingIdSchema } from "@lib/shared-schemas";
import { z } from "zod";

const schema = z.object({
  shipmentIdentifier: shippingIdSchema(),
});

If you want a more ergonomic API (like z.shippingId()), use the "re-export pattern": create a custom module that exports everything from Zod and adds your own helpers (source, source):

// custom-zod.ts
export * from "zod";
export const shippingId = () =>
  z.string().regex(/^SHIP-\d{6}$/, { message: "Invalid shipment ID" });

// usage
import * as z from "./custom-zod";

const schema = z.object({
  shipmentIdentifier: z.shippingId(),
});

This pattern gives you the API you want, but you must import from your custom module instead of the original Zod package.

Community packages like zod-extend exist, but they don't include type aliases like z.infer<> and aren't officially recommended (source). A plugin system (z.extend(plugin)) has been proposed, but it's not implemented yet (source).

If this answers your question, please close the issue! If you need a more tailored example, let me know.

To reply, just mention @dosu.

---

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