Zod discriminated union "other string" option

[BrendanC23]

I'd like to be able to create a Zod schema like the following:

z.discriminatedUnion("val", [
  z.object({
    val: z.literal("A"),
    a: z.string().min(1),
  }),
  z.object({
    val: z.string(),
    a: z.string(),
  })
]);

Here, a is only required when val is A. For any other value of val, it can be empty. Currently, Zod's discriminated union feature doesn't allow non-literal discriminator values and so z.string() cannot be used.

I've also tried writing this with a regular z.union(). However, an input of { val: "A", a: "" } successfully parses because the second union member is matched (see this playground link).

z.union([
  z.object({
    val: z.literal("A"),
    a: z.string().min(1),
  }),
  z.object({
    val: z.string(),
    a: z.string(),
  })
]);

Is there a way to build a schema that can have a z.string() option as a fallback for the discriminated union?

[dosubot[bot]]

Zod's discriminatedUnion only supports literal values for the discriminator key, so you can't use z.string() as a fallback option in the way you described. This is an intentional design decision for performance and error reporting reasons (see discussion, another discussion, confirmation in v4).

For your use case—where a is required only when val is "A", and otherwise can be empty—there are a few workarounds:

1. Use a custom transform/refinement:
You can define a base schema and use .refine() or .superRefine() to enforce the conditional requirement:

const schema = z.object({
  val: z.string(),
  a: z.string(),
}).superRefine((data, ctx) => {
  if (data.val === "A" && !data.a) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: "`a` is required when `val` is 'A'",
      path: ["a"],
    });
  }
});

2. Use the upcoming z.switch API (Zod 4+):
z.switch allows you to select a schema at parse-time based on the input, supporting fallback cases (see discussion). Example:

const schema = z.switch((input) => {
  if (input.val === "A") {
    return z.object({ val: z.literal("A"), a: z.string().min(1) });
  }
  return z.object({ val: z.string(), a: z.string() });
});

3. Community workaround with orFallback:
Some users wrap a discriminatedUnion with a custom function to provide fallback parsing (see example).

If your question is answered, please close the issue! If you need a more tailored example, let me know your Zod version and I can help further.

To reply, just mention @dosu.

---

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

[BrendanC23]

The discriminatedUnion was included in Zod 4 and hasn't been deprecated. The linked issue was closed, and it seems like the experimental switch API isn't going to be implemented.

The orFallback option is interesting, but it doesn't seem to support a fallback schema, only a literal like (value) => ({ type: "unknown", value } as const).

[BrendanC23]

It seems like the best option is to do the following:

z.union([
  z.object({
    val: z.literal("A"),
    a: z.string().min(1),
  }),
  z.object({
    val: z.string().refine(str => str !== "A"),
    a: z.string(),
  })
]);

This works, but it isn't ideal because it uses a z.union() instead of a z.discriminatedUnion() and the refine() call must be kept up-to-date if new union members are added or the existing ones change. It would be great if there was support for non-literal values in discriminated unions, or a straightforward way to designate a fallback schema if none of the discriminated union options are met.