How to create schema for open-ended union using zod 4.0

[chenxin-yan]

Hi, I am wondering how to use zod schema to model this type : "a" | "b" | (string & {}) so that I got autocomplete on my editor but any string would pass the parsing.

[dosubot[bot]]

Hi @chenxin-yan! I'm Dosu and I’m helping the zod team.

You can define a Zod 4 schema that accepts "a", "b", or any string using z.union([z.literal("a"), z.literal("b"), z.string()]). This will validate any string at runtime, including "a" and "b":

import { z } from "zod";

const schema = z.union([z.literal("a"), z.literal("b"), z.string()]);

However, due to how TypeScript infers types, the resulting type will be just string, so you won't get autocomplete for "a" and "b" in your editor. This is a TypeScript behavior—when you union specific string literals with string, the type collapses to string, and literal suggestions are lost. Zod doesn't have a way to change this inference or provide literal autocomplete for open-ended unions like this [docs].

If you want autocomplete for "a" and "b" during development, you could use a helper type for hints, but at runtime, the schema will always accept any string. There isn't a native Zod or TypeScript workaround to get both literal autocomplete and open-ended string validation in one type.

Let me know if this answers your question—feel free to close the issue if so!

To reply, just mention @dosu.

---

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

[rijenkii]

This seems to work:

import { z } from "zod/v4";

const schema = z.union([
  z.literal("a"),
  z.literal("b"),
  z.string().transform((x) => x as string & {}),
]);
type Schema = z.infer<typeof schema>;
// type Schema = "a" | "b" | (string & {})

You can extract that transformed string into a helper method if you use it often:

const nonLiteralString = () => z.string().transform((x) => x as string & {});

const schema = z.union([
  z.literal("a"),
  z.literal("b"),
  nonLiteralString(),
]);

[chenxin-yan]

Currently, I an doing this which works:

const schema = z.string() as z.ZodType<"a" | "b" | (string & {})>;

[rijenkii]

Also a valid solution, probably marginally more performant.

Unless you want to use z.toJSONSchema, then none of our solutions work -- mine gets rejected because it uses transform, yours results in a simple { "type": "string" } json schema.

If you or anyone else wants to do this and not lose the ability to convert to json schema, this seems to work:

const schema = z.union([
  z.literal("a"),
  z.literal("b"),
  z.string() as z.ZodType<string & {}>,
]);
type Schema = z.infer<typeof schema>;
// type Schema = "a" | "b" | (string & {})

Resulting schema is { "anyOf": [{ "type": "string", "const": "a" }, { "type": "string", "const": "b" }, { "type": "string" }] }.

[chenxin-yan]

this looks good. It maintains the semantic of zod by only asserting the type for the string