Api

Conversion Mapping

How Zod types and validations are mapped to Mongoose.

Conversion Mapping

@nullix/zod-mongoose automatically maps Zod's built-in validations and transformations to their corresponding Mongoose SchemaType options.

Automatic Validation Mapping

The following Zod checks are directly converted to Mongoose SchemaType options:

Zod Check	Mongoose Option	Target Types
`.min(n)`	`minlength: n`	`z.string()`
`.max(n)`	`maxlength: n`	`z.string()`
`.length(n)`	`minlength: n`, `maxlength: n`	`z.string()`
`.regex(re)`	`match: re`	`z.string()`
`.trim()`	`trim: true`	`z.string()`
`.toLowerCase()`	`lowercase: true`	`z.string()`
`.toUpperCase()`	`uppercase: true`	`z.string()`
`.min(n)` / `.positive()`	`min: n`	`z.number()`, `z.date()`
`.max(n)` / `.negative()`	`max: n`	`z.number()`, `z.date()`
`.uuid()`	`type: Schema.Types.UUID`	`z.string()`
`.datetime()`	`type: Date`	`z.string()`
`.date()`	`type: Date`	`z.string()`
`.time()`	`type: String`	`z.string()`

Type Conversion Table

The following table shows how Zod types are mapped to Mongoose types by default.

Zod Type	Mongoose Type	Notes
`z.string()`	`String`	Required by default unless `.optional()` is used.
`z.string().uuid()`	`mongoose.Schema.Types.UUID`	Maps to Mongoose's native UUID type.
`z.string().datetime()`	`Date`	Maps to Mongoose `Date` for automatic parsing and indexing.
`z.string().date()`	`Date`	Maps to Mongoose `Date`.
`z.number()`	`Number`
`z.boolean()`	`Boolean`
`z.date()`	`Date`
`z.bigint()`	`BigInt`	Fallback to `Number` if `BigInt` is not supported. Use `withMongoose` with `type: 'Long'` for 64-bit integers.
`z.enum()`	`String`	Includes Mongoose `enum` validation.
`z.nativeEnum()`	`String`	Includes Mongoose `enum` validation.
`z.string().trim()`	`String`	Automatically sets `trim: true`.
`z.string().toLowerCase()`	`String`	Automatically sets `lowercase: true`.
`z.string().min(5)`	`String`	Automatically sets `minlength: 5`.
`z.array()`	`[]`	Mapped to a Mongoose array of the inner type.
`z.set()`	`[]`	Mapped to a Mongoose array of the value type.
`z.tuple()`	`[]`	Mapped to a Mongoose array of the first item's type.
`z.record()`	`Map`	Mapped to a Mongoose `Map` with `of` type.
`z.map()`	`Map`	Mapped to a Mongoose `Map` with `of` type.
`z.object()`	`Nested Object`	Mapped to a nested Mongoose schema or subdocument.
`z.intersection()`	`Nested Object`	Merges the definitions of both branches into a single object.
`z.union()`	`Schema.Types.Union` (primitives) or `Nested Object` (objects)	Mapped to `Union` for primitives, merged into an object for `z.object()` unions. Others fallback to `Mixed`.
`z.xor()`	`mongoose.Schema.Types.Mixed`	Non-inclusive union. Maps to `Mixed` with a custom Zod-based validator to enforce mutual exclusivity.
`z.discriminatedUnion()`	`Mongoose Discriminator`	Maps to native Mongoose discriminators. Common fields are automatically moved to the base schema.
`zObjectId()`	`mongoose.Schema.Types.ObjectId`	Specialized helper for ObjectIds. By default, it is omitted from the generated Mongoose schema to let Mongoose handle its auto-generation.
`zBuffer()`	`mongoose.Schema.Types.Buffer`	Specialized helper for Buffers.
`zPopulated()`	`mongoose.Schema.Types.ObjectId`	Helper for fields that can be either an `ObjectId` or a populated object.
`z.instanceof(Buffer)`	`mongoose.Schema.Types.Buffer`
`z.instanceof(ObjectId)`	`mongoose.Schema.Types.ObjectId`
`z.literal()`	`String` / `Number` / `Boolean`	Mapped to the literal's type with a Mongoose `enum` constraint.
`z.any()` / `z.unknown()`	`mongoose.Schema.Types.Mixed`	Fallback for unhandled types.

Unhandled and Unsupported Zod Types

The following Zod types are currently not explicitly handled or are unsupported by nature and will fall back to Mongoose.Schema.Types.Mixed unless a custom type is provided via withMongoose.

Zod Type	Current Status	Recommended Alternative
`z.readonly()`	`Base Type`	Automatically unwrapped, applies `readOnly: true` metadata.
`z.promise()`	Unsupported	Not applicable for database schemas
`z.function()`	Unsupported	Not applicable for database schemas
`z.void()` / `z.never()`	Unsupported

Note: Types like z.branded(), z.readonly(), z.pipeline(), z.preprocess(), and z.transform() are automatically unwrapped to their underlying base type during conversion.

Usage

Learn how to use zod-mongoose in your application.

Core Functions

The main functions for converting Zod schemas to Mongoose.