Loose autocomplete with enums / don't error on unknown values

[matthew-gladman-oua]

Hi, is it currently possible to give Zod a list of values in an enum, but during parsing to not error. I want the equivalent of this TypeScript:

type Example = {
    example: "hi" | "hi2" | "hi3" | (string & {})
}

const hello: Example = {
    example: "hi3" // known, auto-complete / intellisense 
}

const hello2: Example = {
    example: "something" // unknown value, doesn't error
}

I still want a list of known values, but to not error if unknown ones appear. Aka, something in between .enum and .string.

Is this currently possible to express in Zod? Or is this a feature request?

Why?

We use Zod heavily for our integrations with various services. For the most part, our internal services and most external ones are built with the presumption of "additions are safe, they do not break the contract". But if we use .enum that is no longer the case. That field will cause parsing to fail if a new enum value is added in; making using .enum dangerous.

[dosubot[bot]]

Hi @matthew-gladman-oua! I'm Dosu and I’m helping the zod team.

Zod doesn't have a built-in "loose enum" feature, but you can get the behavior you want by using a union: z.union([z.enum([...]), z.string()]). This gives you TypeScript autocomplete for your known values, but will also accept any string at runtime—so unknown values won't error. Example:

import { z } from "zod";

const ExampleSchema = z.object({
  example: z.union([z.enum(["hi", "hi2", "hi3"]), z.string()])
});

// TypeScript type:
type Example = z.infer<typeof ExampleSchema>;
// { example: "hi" | "hi2" | "hi3" | (string & {}) }

ExampleSchema.parse({ example: "hi3" }); // passes
ExampleSchema.parse({ example: "something" }); // also passes

This pattern isn't a first-class Zod feature, but it works because of how TypeScript unions and Zod's combinators interact. If you want to see this as a dedicated feature, feel free to tag @colinhacks for further discussion. If this solves your problem, please close the issue!

For more on how Zod's .enum() and .string() work, see the implementation details here.

To reply, just mention @dosu.

---

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

[matthew-gladman-oua]

@dosu Unfortunately, this effectively "destroys" the enum values and it just becomes a string, the enum does nothing now.

[dosubot[bot]]

You're right—when you use z.union([z.enum([...]), z.string()]), TypeScript widens the type to just string, so you lose autocomplete for the enum values. This is a TypeScript type system behavior, not something Zod can control at the schema level. Zod's .enum() only allows the specified values and will error on unknowns, while .string() accepts anything but doesn't provide suggestions.

There isn't a built-in or documented way in Zod to get both runtime acceptance of any string and TypeScript autocomplete for a fixed set of values. This is a well-known TypeScript limitation: once you union a string literal type with string, you lose the literal completions in editors. You can see this reflected in Zod's core code and API design (source).

Some teams work around this by using JSDoc comments or custom editor plugins to provide suggestions, but these don't affect the type system or runtime validation. If you have a specific workflow or editor in mind, I can help brainstorm further.

If this answers your question, please close the issue!

To reply, just mention @dosu.

---

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

[matthew-gladman-oua]

As recommended by the bot: @colinhacks

[rijenkii]

See #4934.

[matthew-gladman-oua]

Brilliant, exactly what I was looking for!

Example in line with the context here:

import { z } from 'zod';

const exampleValues = {
  hi: 'hi',
  hi2: 'hi2',
  hi3: 'hi3',
} as const;

const exampleSchema = z.object({
  example: z.union([z.enum(exampleValues), z.string() as z.ZodType<string & {}>]),
});

type Example = z.infer<typeof exampleSchema>;

const hello: Example = {
  example: 'hi', // known, auto-complete / intellisense
};

const hello2: Example = {
  example: 'something', // unknown value, doesn't error
};