Using objects like literals

[Bugrabugra]

Hello there,

We are migrating our codebase to TS and we will use Zod 4. I am creating our schemas for forms and backend responses. Here I got stuck.

In one of our GET endpoint, the result is like this:

[
  {
    _id: string,
    status: "PENDING" | "SENT",
    audit: {
      createdAt: string,
      createdBy: string,
      updatedAt: string,
      updatedBy: string
    },
    // tricky part here
    vehicle OR forklift OR gateway : {
      _id: string
    },
    command: string
  }
]

Here what I do:

import { z } from "zod";
import { _ID, AuditSchema } from "./shared/api";

const Command = z.string().min(1).max(1000);

const ID = z.object({
  _id: _ID,
});

const VehicleCommandSchema = z.object({
  vehicle: ID,
  command: Command,
});

const ForkliftCommandSchema = z.object({
  forklift: ID,
  command: Command,
});

const GatewayCommandSchema = z.object({
  gateway: ID,
  command: Command,
});

const Status = z.union([
  z.literal("PENDING"),
  z.literal("SENT"),
]);

const BaseCommandSchema = z.object({
  _id: _ID,
  status: Status,
  audit: AuditSchema,
});

const CommandSchema = z.union([
  BaseCommandSchema.extend(VehicleCommandSchema.shape),
  BaseCommandSchema.extend(ForkliftCommandSchema.shape),
  BaseCommandSchema.extend(GatewayCommandSchema.shape),
]);

export type Command = z.infer<typeof CommandSchema>;

My aim was if I create an object from Command, when I parse it, I would like to see vehicle, forklift or gateway object too. A response should have ONLY ONE of these objects ({vehicle: {_id: string}, command: string} | {forklift: {_id: string}, command: string} | {gateway: {_id: string}, command: string}) and the other base schema (_id, status, audit). But when I do this:

const command: Command = {
  _id: "123456789012345678901234",
  status: "PENDING",
  audit: {
    createdAt: "2021-01-01T00:00:00.000Z",
    updatedAt: "2021-01-01T00:00:00.000Z",
    createdBy: "123456789012345678901234",
    updatedBy: "123456789012345678901234",
  },
  command: "",
  vehicle: {
    _id: "123456789012345678901234",
  }
};

const obj = CommandSchema.parse(command);

console.log(obj);

and put "." after obj in console.log, I cannot see vehicle object. How can I force my schema to have ONE of these CommandValidationSchema items (vehicle or forklift or gateway) ?

Thank you in advance!

[dosubot[bot]]

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

To enforce that exactly one of vehicle, forklift, or gateway is present in each object, use a z.union of strict object schemas—each with only one of those keys, plus your shared fields. In Zod 4, the recommended way is to use z.strictObject() for each branch. This ensures that objects with more than one of the mutually exclusive keys will fail validation, both at runtime and in TypeScript types. For example:

const VehicleCommand = z.strictObject({
  _id: _ID,
  status: Status,
  audit: AuditSchema,
  vehicle: ID,
  command: Command,
});

const ForkliftCommand = z.strictObject({
  _id: _ID,
  status: Status,
  audit: AuditSchema,
  forklift: ID,
  command: Command,
});

const GatewayCommand = z.strictObject({
  _id: _ID,
  status: Status,
  audit: AuditSchema,
  gateway: ID,
  command: Command,
});

const CommandSchema = z.union([
  VehicleCommand,
  ForkliftCommand,
  GatewayCommand,
]);

This pattern enforces mutual exclusivity at the key level—if an object has more than one of vehicle, forklift, or gateway, it will fail validation. If you use .extend() with non-strict objects, extra keys may be allowed, so .strictObject() is key here. See the Zod 4 changelog for details on .strictObject().

If you still can't see the vehicle property after parsing, double-check that your input matches the schema exactly and that you're not running into a TypeScript inference issue. If your problem is with intellisense or type inference rather than runtime validation, let me know!

If this solves your problem, please close the issue.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[Bugrabugra]

@dosu

I have problems with intellisense. Your solution didn't solve my problem.

[dosubot[bot]]

This is a TypeScript limitation, not a Zod issue: when you use z.union() of object schemas without a shared discriminator key, TypeScript intellisense will only show properties common to all union members. To get reliable intellisense and type narrowing (so you see vehicle, forklift, or gateway as expected), you need to use a discriminated union—meaning each object in the union must have a shared property (like type: "vehicle" | "forklift" | "gateway"), and you use z.discriminatedUnion() with that key. This lets TypeScript narrow the type based on the discriminator and gives you full intellisense for the mutually exclusive keys. See the Zod docs and this explanation.

If you can't add a discriminator key, you can use type assertions or manual type guards after parsing, but intellisense in editors won't improve—this is a known TypeScript behavior, not something Zod can change (reference). If you want a concrete example of the discriminated union pattern or have a specific intellisense workflow in mind, let me know! If this answers your question, please close the issue.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.