Consider changing input type of object schemas with Valibot v2

[fabian-hiller]

Discussed in #1366

^{Originally posted by mrft December 2, 2025}
I'll start with a simple example:

  const SimpleSchema = V.object({ x: V.number() });
  type TSimpleInput = V.InferInput<typeof SimpleSchema>; // { x: number; } but in practice { x: number; [key: string]: any; }
  type TSimpleOutput = V.InferOutput<typeof SimpleSchema>; // { x: number; }
  console.debug(
    "simple object parse result:",
    V.safeParse(SimpleSchema, { x: 5, y: 7 })
  );

So the inferred input type is stricter than what safeParse will allow.

This bug (in my opinion) is also reflected in the intersection docs: https://valibot.dev/guides/intersections/, which further suggests that the implementation is not in line with people's intuition about how it should work:

These docs use the following example:

// TypeScript
type Intersect = { foo: string } & { bar: number };

// Valibot
const IntersectSchema = v.intersect([
  v.object({ foo: v.string() }),
  v.object({ bar: v.number() }),
]);

but in reality we get:

// TypeScript
type Intersect = { foo: string; [key: string]: any; } & { bar: number; [key: string]: any; };

// Valibot
const IntersectSchema = v.intersect([
  v.object({ foo: v.string() }),
  v.object({ bar: v.number(); }),
]);

because when parsing, it will not complain about extra properties, whereas the typescript compiler would complain about extra properties in the first version.

This gets worse when using a strictObject:

  const firstSchema = v.strictObject({
    a: v.number(),
    b: v.string(),
  });
  type TFirstInput = v.InferInput<typeof firstSchema>; // { a: number; b: string }

  const secondSchema = v.strictObject({
    c: v.number(),
  });
  type TSecondInput = v.InferInput<typeof secondSchema>; // { c: number; }

  const intersectSchema = v.intersect([firstSchema, secondSchema]);
  type TIntersectInput = v.InferInput<typeof intersectSchema>; // { a: number; b: string; c: number; }

  console.debug(
    "intersectSchema parse result:",
    v.safeParse(intersectSchema, { a: 1, b: "foo", c: 3 })
  ); // => {
  // typed: false,
  // success: false,
  // output: { a: 1, b: "foo", c: 3 },
  // issues: [
  //     'Invalid key: Expected never but received "c"',
  //     'Invalid key: Expected never but received "a"',
  // ]  

This is not inline with the inferred types, but also unintuitive (as well as useless) from a user perspective.

(Unfortunately zod has the exact same bug)

REMARK: if this is how it is supposed to work, then toJsonSchema should also be updated to avoid simply producing { allOf: [ { additionalProperties: false }, { ... } ] } as that would have the same problem (it should be { type: "object", unevaluatedProperties: false, allOf [ { ... additionalProperties undefined }, { ... additionalProperties undefined } ] } without the additionalProperties key, not supported in JSON-Schema draft‑07 but introduced since the JSON Schema 2019‑09 specs).

I let Github Copilot crunch on the issue to make it behave the way I would expect it to behave: https://github.com/mrft/valibot/tree/feat-intersect-strict

[dosubot]

You're right that there's a mismatch between Valibot's inferred TypeScript types and its runtime parsing for object and intersect schemas. By default, object schemas strip unknown properties from the output but do not error on extra properties at runtime, even though the inferred input type appears strict. This means safeParse will accept extra keys, which TypeScript would reject based on the inferred type. If you want runtime errors for extra properties, you need to use strictObject, which forbids unknown entries and returns an issue for the first extra key found (docs, code).

For intersections, the situation is trickier. The intersect schema validates each schema independently and merges their outputs, but it only enforces strictness if all intersected schemas are strict. If you intersect two object schemas, extra properties are not rejected at runtime, even though the inferred input type is strict. If you intersect two strictObject schemas, the intersection will often fail in unintuitive ways, because each schema forbids keys from the other, leading to validation errors even for valid-looking inputs (example, docs).

This mismatch is a known issue and is being tracked by the maintainers (discussion, issue). There's also ongoing exploration of solutions, including the experimental feat-intersect-strict branch you referenced. In the meantime, the recommended workaround is to merge object schemas instead of using intersect when you want strict property enforcement, or to use objectWithRest/strictObject as appropriate (workaround).

For JSON Schema output, the current approach can generate unsatisfiable schemas when intersecting strict objects, due to conflicting additionalProperties: false constraints. The maintainers are aware and suggest removing additionalProperties: false from individual objects in allOf, or using unevaluatedProperties: false at the parent level if your JSON Schema version supports it (details).

If you need stricter compile-time checks, you can use TypeScript utility types like Shape<T> or Exact<T, U> to help ensure your schema matches your types, but these are not enforced by Valibot itself and require extra boilerplate (discussion).

Let me know if you want more details on any of these workarounds or the status of the experimental branch!

To reply, just mention @dosu.

---

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

   

[fabian-hiller]

I removed the "bug" label as the current behavior is intended.

[ikeyan]

@fabian-hiller
I understand that this is "intended behavior" regarding the current implementation logic (where intersect acts as a logical AND pipeline of validators). However, from the perspective of TypeScript's type system and structural composability, I believe the current DX for strict objects has a significant design gap.

Here is my perspective and a proposal:

1. Separation of "Shape Definition" and "Excess Property Check"

In TypeScript, { x: number } and { x: number; [key: string]: any } are structurally compatible in terms of assignability. The "Excess Property Check" is essentially a linter-like feature for developer convenience, not a fundamental property of the type's shape.

Currently, strictObject bakes this "validation constraint" directly into the "shape definition." This makes the schema non-extensible. When we try to intersect two strictObject schemas, we get never (nothing is accepted) because:

• Validator A says: "I only allow key a."
• Validator B says: "I only allow key b."
• Logical AND (Intersection): "I allow nothing."

While this is logically correct for a pipeline, it is counter-intuitive for users expecting structural merging (like TypeScript's & operator of inferred types).

2. Proposal: Introduce v.merge and v.strict utilities

If changing intersect is difficult, I propose introducing a structural merge utility and separating the strictness check.
This allows us to define loose shapes, merge them, and apply strictness at the end:

const A = v.object({ a: v.string() });
const B = v.object({ b: v.number() });

// 1. Structural Merge: creates a new object schema by merging entries
const Merged = v.merge([A, B]); // equivalent to v.object({ a: v.string(), b: v.number() })

// 2. Apply Strictness: a wrapper that marks the object(s) as strict
const C = v.strict(Merged); // equivalent to v.strictObject({ a: v.string(), b: v.number() })

3. Handling Variants or Union of Objects

This approach is also crucial for union and variant. Currently, it is very hard to "extend" a variant with common properties in a strict manner.

v.merge and v.strict should ideally support:

• merge([Object, Object]): Merges entries.
• merge([Union<Objects> | Variant, Object]): Distributes the object into each union member (preserving the discriminator if it's a variant).
• strict(Union<Objects> | Variant): Automatically applies strictness to all underlying object schemas. This is essential for making polymorphic API schemas strict without manual re-definition.

Notes:

• I believe v.merge should throw an error (and cause a type error) if it encounters duplicate keys rather than silently overwriting them. If a user intends to overwrite a property, they should be explicit by using v.omit before merging. This prevents subtle bugs and aligns with Valibot's "explicit" philosophy.
• I think merge([Union, Union]) might be an edge case (Cartesian product explosion), so supporting Union + Object is most pragmatic.

Summary

If we view intersect as a "Logical AND" and keep it as is, we are missing a "Structural Merge" primitive. Adding v.merge and a composable v.strict(schema) wrapper would solve this issue while keeping Valibot's core logic intact.

What do you think about this direction?