Strictly enforce a schema input using ZodType

[abarani]

I'm trying to use ZodType to enforce that a schema matches a specific input type.

Take this sample code:

import * as z from "zod"

type Schema = z.ZodType<unknown, { title?: string | undefined }>

// z.input<typeof schema1> = {
//     title?: string | undefined;
// }
//
// No errors as expected.
const schema1 = z.object({ title: z.string().optional() }) satisfies Schema

// Errors out as expected with:
//  Type 'number' is not assignable to type 'string'. (1360)
const schema2 = z.object({ title: z.number() }) satisfies Schema

// z.input<typeof schema3> = {
//     title: string;
// }
//
// ⚠️ This does *not* error even if "title" is not optional.
const schema3 = z.object({ title: z.string() }) satisfies Schema

In this case schema3 does not error, even though title is not optional in the schema implementation.

Is there a way to strictly enforce, at the type level, that a Zod schema strictly matches (including optional/required in this case) a specific input type?
Any advice or examples would be appreciated!

[dosubot[bot]]

Hi @abarani! I'm Dosu and I’m helping the zod team.

TypeScript's structural typing means that two types are considered compatible if their shapes match, even if optional/required properties differ. This is why schema3 does not error: { title: string } is assignable to { title?: string | undefined } because required properties are compatible with optional ones, but not vice versa. This is a TypeScript behavior, not something Zod can override at the type level [docs].

Zod's generics and the satisfies operator can't strictly enforce optionality in this way. Even constraining with ZodType<unknown, { title?: string | undefined }> won't catch the mismatch, since TypeScript allows the assignment [docs].

If you need strict enforcement (including optional/required), you can use a helper type to compare the inferred input type of your schema to your desired type, for example:

type StrictMatch<A, B> =
  (<T>() => T extends A ? 1 : 2) extends
  (<T>() => T extends B ? 1 : 2) ? true : false;

type ExpectStrict<T extends true> = T;

// Usage:
type SchemaInput = { title?: string | undefined };
type Schema3Input = z.input<typeof schema3>;
type IsStrict = StrictMatch<Schema3Input, SchemaInput>;
type _Check = ExpectStrict<IsStrict>; // Error if not strictly equal

This will error if the types are not strictly equal, including optionality. You can use this pattern in your tests or as a type assertion.

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}    

[abarani]

Based on the bot suggestion I came up with an assertion function:

export const assertSchemaInput: <T>() => <U extends z.core.$ZodType>(
    result: [T] extends [z.input<U>] ? [z.input<U>] extends [T] ? U : never : never,
) => void = () => () => { };

Example usage:

import * as z from "zod"

type Input = { title?: string | undefined }
type Schema = z.ZodType<unknown, Input>

// z.input<typeof schema1> = {
//     title?: string | undefined;
// }
const schema1 = z.object({ title: z.string().optional() }) satisfies Schema
assertSchemaInput<Input>()(schema1);

// z.input<typeof schema3> = {
//     title: string;
// }
const schema3 = z.object({ title: z.string() }) satisfies Schema
assertSchemaInput<Input>()(schema3);
//                         ^^^^^^^ Type error

It's not the most elegant solution but it works for my use case.