Variant schemas with shared elements

[alexwgraves]

Hi there! I have a use case that is mostly but not entirely a discriminated union, namely that my schemas share some keys but not others. I've been using v.variant to great success, but I'm finding that as I add more variants, I'm running up against TS errors (ex. "The inferred type of this node exceeds the maximum length the compiler will serialize. An explicit type annotation is needed."). Here's a simplified example of what I'm currently doing:

// shared across all types in variant
const CommonSchema = v.object({
  species: v.string(),
});

const CatSchema = v.object({
  ...CommonSchema.entries,
  type: v.literal('cat'),
  cat: v.object({
    isLongHair: v.boolean(),
  }),
});

const DogSchema = v.object({
  ...CommonSchema.entries,
  type: v.literal('dog'),
  dog: v.object({
    breed: v.string(),
    group: v.string(),
  }),
});

const BirdSchema = v.object({
  ...CommonSchema.entries,
  type: v.literal('bird'),
  bird: v.object({
    canFly: v.boolean(),
  }),
});

const AnimalSchema = v.variant('type', [
  CatSchema,
  DogSchema,
  BirdSchema,
]);
type Animal = v.InferOutput<typeof AnimalSchema>;

The generated type for Animal is as follows, which is a bit redundant given that every option contains the shared species property.

type Animal = {
    type: "cat";
    cat: { isLongHair: boolean };
    species: string;
} | {
    type: "dog";
    dog: { group: string };
    species: string;
} | {
    type: "bird";
    bird: { canFly: boolean };
    species: string;
};

Is there a way to do this that results in a type more like the following?

type Animal = {
  species: string;
} & (
  | {
      type: 'cat';
      cat: { isLongHair: boolean };
    }
  | {
      type: 'dog';
      dog: { group: string };
    }
  | {
      type: 'bird';
      bird: { canFly: boolean };
    }
);

This would greatly reduce the size of the type (as my schemas have well over a dozen shared properties), while still preserving the benefits of the discriminated union. I'm basically thinking of something like this, where the third argument is a common/shared schema that they would all use:

const AnimalSchema = v.variant(
  'type',
  [CatSchema, DogSchema, BirdSchema],
  CommonSchema,
);

Unless there's a way to already do this that I'm missing? Thank you!

[dosubot[bot]]

Hi @alexwgraves! I'm Dosu and I’m helping the valibot team.

Valibot doesn't currently support factoring out shared properties in variant schemas via a third argument or built-in feature in v.variant—each variant option must include all its properties, so the union type repeats shared keys and can get verbose as you add more variants source.

To achieve the intersection type you want (shared properties factored out), the recommended pattern is to use v.intersect to combine your shared schema with the variant schema. This produces a type like {shared} & (variant union) and helps reduce redundancy and TypeScript complexity source.

Here's how you can do it:

const CommonSchema = v.object({
  species: v.string(),
});

const CatSchema = v.object({
  type: v.literal('cat'),
  cat: v.object({ isLongHair: v.boolean() }),
});

const DogSchema = v.object({
  type: v.literal('dog'),
  dog: v.object({ breed: v.string(), group: v.string() }),
});

const BirdSchema = v.object({
  type: v.literal('bird'),
  bird: v.object({ canFly: v.boolean() }),
});

const AnimalVariant = v.variant('type', [
  CatSchema,
  DogSchema,
  BirdSchema,
]);

const AnimalSchema = v.intersect([CommonSchema, AnimalVariant]);
type Animal = v.InferOutput<typeof AnimalSchema>;

This results in the desired type structure:

type Animal = {
  species: string;
} & (
  | { type: 'cat'; cat: { isLongHair: boolean } }
  | { type: 'dog'; dog: { breed: string; group: string } }
  | { type: 'bird'; bird: { canFly: boolean } }
);

A couple of caveats: if you have conflicting keys between the shared schema and any variant, v.intersect will produce a validation issue rather than silently dropping data source. Also, deep nesting or very large unions can still hit TypeScript's type complexity limits, but this pattern helps minimize redundancy.

There’s no indication in the docs or codebase that v.variant will support a shared schema argument or automatic factoring out of shared properties anytime soon source. For now, manual composition with v.intersect is the best practice for this use case.

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[alexwgraves]

My case was a bit complicated by variant-specific checks, but I was able to add those checks on after creating an intersect schema by using v.isOfType to distinguish between my different variants. A combination of that and the suggestion above solved my problem!

[fabian-hiller]

Great! But if you still need an answer from a human feel free to reach out! There is also a community on Discord that is happy to help.