Valibot plugin emits unparameterized `GenericSchema`, causing nested array output types to become `unknown[]`

[yslpn]

Description

The Valibot plugin currently emits some schemas as a bare v.GenericSchema when the generated schema contains v.lazy(...) references.

Because v.GenericSchema defaults to GenericSchema<unknown, unknown>, any other schema that uses that generated schema inside v.array(...) loses the array element type. The resulting v.InferOutput<typeof schema> contains unknown[] instead of the expected referenced type array.

I can submit a pull request if the preferred fix is to avoid emitting the GenericSchema annotation and let TypeScript infer the concrete schema type.

Bug description

Given generated code like this:

// Actual
export const vChild: v.GenericSchema = v.object({
  id: v.optional(v.number()),
  next: v.optional(v.lazy(() => vChild)),
});

export const vParent = v.object({
  id: v.number(),
  children: v.optional(v.array(vChild)),
});

TypeScript infers:

v.InferOutput<typeof vParent>
// {
//   id: number;
//   children?: unknown[] | undefined;
// }

Expected:

v.InferOutput<typeof vParent>
// {
//   id: number;
//   children?: Child[] | undefined;
// }

This happens because v.GenericSchema without type parameters is equivalent to v.GenericSchema<unknown, unknown>.

A minimal Valibot-only reproduction (you can check in browser in valibot's playground):

import * as v from 'valibot';

type Child = {
  id?: number;
};

type Parent = {
  id: number;
  children?: Child[];
};

const childSchema: v.GenericSchema = v.object({
  id: v.optional(v.number()),
});

const parentSchema = v.object({
  id: v.number(),
  children: v.optional(v.array(childSchema)),
});

const parent: Parent = {
  id: 1,
  children: [],
};

const parsedParent = v.parse(parentSchema, parent);

export const result: Parent = parsedParent;

TypeScript error:

Type '{ id: number; children?: unknown[] | undefined; }' is not assignable to type 'Parent'.
  Types of property 'children' are incompatible.
    Type 'unknown[] | undefined' is not assignable to type 'Child[] | undefined'.
      Type 'unknown[]' is not assignable to type 'Child[]'.
        Type 'unknown' is not assignable to type 'Child'.

The generated schema should let TypeScript infer the concrete schema type:

// Expected
export const vChild = v.object({
  id: v.optional(v.number()),
  next: v.optional(v.lazy(() => vChild)),
});

This keeps the output type intact, so v.array(vChild) is inferred as Child[] instead of unknown[].

Reproducible example or configuration

Minimal package setup:

{
  "type": "module",
  "scripts": {
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@hey-api/openapi-ts": "0.98.1",
    "valibot": "1.3.1"
  },
  "devDependencies": {
    "typescript": "5.8.3"
  }
}

Minimal Hey API config:

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: './openapi.yaml',
  output: './generated',
  plugins: [
    {
      enums: 'javascript',
      name: '@hey-api/typescript',
    },
    {
      name: 'valibot',
    },
  ],
});

Command:

npx openapi-ts
npx tsc --noEmit

There is also a reduced Valibot-only reproduction in:

examples/valibot-generic-schema-repro

Run it with:

npm install
npm run typecheck

OpenAPI specification (optional)

openapi: 3.1.0
info:
  title: Valibot GenericSchema Repro
  version: 1.0.0
paths:
  /parents:
    get:
      operationId: getParents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Parent'
components:
  schemas:
    Parent:
      type: object
      required:
        - id
      properties:
        id:
          type: number
        children:
          type: array
          items:
            $ref: '#/components/schemas/Child'
    Child:
      type: object
      properties:
        id:
          type: number
        next:
          $ref: '#/components/schemas/Child'

The recursive Child.next reference makes the Valibot plugin generate a schema that needs v.lazy(...). The issue is not the lazy runtime shape itself, but the emitted bare v.GenericSchema type annotation. Removing that annotation lets TypeScript infer the concrete Valibot schema type.

System information (optional)

@hey-api/openapi-ts: 0.98.1
valibot: 1.3.1
typescript: 5.8.3
node: 24.16.0
npm: 11.13.0

[pullfrog]

Plan for #4027: Valibot GenericSchema causing unknown[] in nested array output types

Root cause

In packages/openapi-ts/src/plugins/valibot/v1/visitor.ts:56-58, the applyModifiers function sets typeName to 'GenericSchema' whenever a schema contains a v.lazy(...) reference:

const typeName: ValibotFinal['typeName'] = result.meta.hasLazy
  ? identifiers.types.GenericSchema
  : undefined;

This typeName is then emitted in shared/export.ts:47 as a type annotation:

.$if(final.typeName, (c) => c.type($.type(plugin.symbols.v).attr(final.typeName!)))

Which produces export const vChild: v.GenericSchema = .... Because v.GenericSchema defaults to v.GenericSchema<unknown, unknown>, any v.array(vChild) resolves to unknown[] instead of Child[].

Fix

One-line change in packages/openapi-ts/src/plugins/valibot/v1/visitor.ts: remove the typeName assignment from applyModifiers (lines 56-58) and all its uses in the return objects. After the change, typeName will always be undefined, which causes the export to omit the type annotation — TypeScript will infer the concrete schema type, fixing the inference chain.

Impact

• hasLazy remains in the ValibotMeta — it's still used by discriminated-union.ts to correctly bail out of v.variant() construction, which is the right behavior.
• The Zod v3 plugin has a similar typeName pattern (using AnyZodObject/ZodTypeAny), but Zod v4 and v4-mini do NOT annotate lazy schemas at all — there's already precedent for omitting this annotation.

Changes needed

File	Change
packages/openapi-ts/src/plugins/valibot/v1/visitor.ts	Remove typeName assignment for lazy schemas in applyModifiers — set typeName to undefined unconditionally, and remove typeName from all return objects in the function
packages/openapi-ts-tests/valibot/v1/__snapshots__/3.1.x/validators-circular-ref/valibot.gen.ts	Update snapshot: remove : v.GenericSchema from vBar and vBaz
packages/openapi-ts-tests/valibot/v1/__snapshots__/3.1.x/validators-circular-ref-2/valibot.gen.ts	Update snapshot: remove : v.GenericSchema from vBar

Verification

1. pnpm tu -- @hey-api/openapi-ts-tests — update snapshots
2. pnpm test -- @hey-api/openapi-ts-tests — run full test suite
3. pnpm typecheck — verify no type errors
4. Visual check: generated vChild const has no type annotation, and v.InferOutput<typeof vParent> resolves children as Child[] instead of unknown[]

Task list (5/5 completed)

• Read learnings file for Valibot plugin architecture
• Find where GenericSchema type annotation is emitted in Valibot plugin
• Understand the lazy/self-referential schema generation flow
• Create a structured plan with implementation steps
• Post plan via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Pro (free via Pullfrog for OSS) ｜ 𝕏}

[mrlubos]

Thanks for reporting @yslpn!

[yslpn]

Thanks for reporting @yslpn!

@mrlubos Thanks! Pullfrog’s plan looks good to me, and the fix seems fairly small.

Would you prefer to trigger Pullfrog to implement the plan, or should I open a PR myself? Happy to do whichever is easier for you.