Impossible to do conditional type with z.$output or z.$input?

[baptisteArno]

type MyMeta = { examples: z.$output extends string ? string[] : never };
const myRegistry = z.registry<MyMeta>();
myRegistry.add(z.string(), { examples: ["test"] });
                                   // ^^^Type 'string[]' is not assignable to type 'never'

I know z.$output resolves to string. So why do I get this type error?

[inkeep-ai-assistant[bot]]

Your type error occurs because conditional types like z.$output extends string ? string[] : never do not work as you expect in this context. z.$output is not a type alias for the output of a specific schema, but rather a generic utility type that requires a type parameter(1)(2). It is meant to be used as z.$output<typeof schema>, not as a bare type.

So, when you write:

type MyMeta = { examples: z.$output extends string ? string[] : never };

You are not passing a schema type to z.$output, so TypeScript cannot resolve what z.$output is, and the conditional type collapses to never(1)(2). That's why assigning a string[] produces the error.

To get the output type of a specific schema (e.g., z.string()), you should write:

type MyMeta<T> = { examples: z.$output<T> extends string ? string[] : never };
const myRegistry = z.registry<MyMeta<typeof z.string()>>();
myRegistry.add(z.string(), { examples: ["test"] });

This way, the conditional type will resolve correctly because z.$output<typeof z.string()> is string(1)(2).

📚 Sources:

1. Zod Core
2. Zod v4 LLMs-Full

---

Have another question? Just tag @inkeep.

[baptisteArno]

@inkeep How to make it work when I declare the type globally?

declare module "zod/v4" {
  interface GlobalMeta {
    examples: z.$output extends string ? string[] : never
  }
}

[inkeep-ai-assistant[bot]]

You cannot use z.$output as a conditional type directly in a global interface like GlobalMeta. The interface GlobalMeta is not generic and does not receive information about the specific schema type, so TypeScript cannot resolve z.$output to a concrete type at this level(1)(2)(3).

If you want per-schema conditional typing (e.g., examples should be string[] for string schemas, number[] for number schemas, etc.), you need to define metadata types locally for each registry or schema, using generics, rather than in a global interface(2)(3).

The recommended pattern is to use a generic metadata type with your registry:

import * as z from "zod";

type MyMeta<T> = { examples: T extends string ? string[] : never };
const myRegistry = z.registry<MyMeta<z.$output<typeof z.string()>>>();

myRegistry.add(z.string(), { examples: ["test"] });

(2)

If you want to extend GlobalMeta for custom fields, you can do so, but you cannot make examples contextually typed per schema instance using only the global interface(1)(3). You can only specify a static type, like examples?: unknown[], in the global interface(1)(3).

📚 Sources:

1. Zod v4 LLMs-Full
2. Metadata and registries
3. V4 meta docs inconsistency (missing "examples")

---

Have another question? Just tag @inkeep.