Reuse existing zod schemas

[ThomasKientz]

Hi,

I want to reuse existing zod schemas I have created and exported from another package, but they are missing extensions like .example("test").

Is there a way to import existing zod schemas and augment them with the plugin?

[dosubot[bot]]

Hi @ThomasKientz! I'm Dosu and I’m helping the express-zod-api team.

Yes, you can import existing Zod schemas from another package and augment them with .example() and other extensions by simply importing the @express-zod-api/zod-plugin in your project. Once the plugin is imported, all Zod schemas—including those you import—gain access to the .example() method and other plugin features. For example:

import { z } from "zod";
import "@express-zod-api/zod-plugin"; // Import the plugin once in your project

import { mySchema } from "my-shared-schemas"; // Your existing schema

const enhancedSchema = mySchema.example("test");

Just make sure the plugin is imported before you use the extension methods. You can find more details and examples in the zod-plugin README.

To reply, just mention @dosu.

---

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

[dosubot[bot]]

Yes, you can augment imported Zod schemas with extensions like .example() using the @express-zod-api/zod-plugin. When you import the plugin, it monkey-patches the prototypes of Zod schema classes at runtime, making .example() available on all ZodType instances created by the Zod package loaded in your process. This means you can call .example() on schemas imported from other packages, as long as both packages use the same (single, deduplicated) Zod version. If there are multiple Zod versions or separate node_modules, the patch may not apply and .example() will not be present. The best practice is to ensure Zod is a peerDependency and hoisted so only one version is used across your project and dependencies [source].

Here’s a code sample:

// In your main project
import { z } from "zod";
import "@express-zod-api/zod-plugin"; // This augments Zod with .example()

// Import your schema from another package
import { userSchema } from "my-shared-schemas";

// Now you can augment it:
const documentedUserSchema = userSchema.example({ name: "Alice", age: 30 });

// Or chain more extensions:
const documentedUserSchema = userSchema
  .example({ name: "Alice", age: 30 })
  .deprecated();

If you run into issues where .example() is missing, check for multiple Zod versions in your node_modules. Both your main project and the package exporting schemas must use the same Zod instance for the plugin to work [source].

To reply, just mention @dosu.

---

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

[ThomasKientz]

What if we are consuming schemas from third party library?

What do you think about a helper to augment standard zod schemas?

import { augment } from "@express-zod-api/zod-plugin";
import { superSchema } from "third-party";

augment(superSchema).example("foo");

[RobinTail]

@ThomasKientz , the augmentation implemented in Zod Plugin works on the level of prototypes (as it was recommended by Colin, the creator or Zod). It makes the custom methods (such as .example()) to exist on every instance of ZodType and it's enough just to import the plugin to do that.

The suggested idea of making a function like augment() is nice, but it would only work for the argument directly, but it won't work for chained calls like this:

schema
  .example()
  .describe()
  .example() // <— this will not work

because Zod methods are immutable — every method you call creates a new instance with a set of methods from its prototype.

Luckily, with Zod 4 the .example() method is just a syntax sugar for .meta({ examples: [] }) — you can use it instead if you're having issues with suggested approach.

import { superSchema } from "third-party";
superSchema.meta({ examples: ["foo"] });

and if you want to enforce more constraints you can add satisfies

import { superSchema } from "third-party";
superSchema.meta({ examples: ["foo"] satisfies Array<z.output<typeof superSchema>> });