Installation

bun add zod-stream zod openai

Version 4 requires Zod 4 and OpenAI 6. The lower-level schema-stream package continues to support both Zod 3.25 and Zod 4.

Progressive streaming

import ZodStream, { isPathComplete } from "zod-stream"
import { z } from "zod"
 
const schema = z.object({
  title: z.string(),
  details: z.object({ count: z.number() }),
  items: z.array(z.object({ label: z.string() }))
})
 
const stream = await new ZodStream().create({
  response_model: { schema },
  completionPromise: async () => {
    const response = await fetch("/api/extract")
    if (!response.body) throw new Error("Missing response body")
    return response.body
  }
})
 
for await (const chunk of stream) {
  if (isPathComplete(["details", "count"], chunk)) {
    console.log(chunk.details?.count)
  }
  console.log(chunk._meta)
}

Progressive chunks represent recursively partial z.input<T>. Nested fields may be missing, primitive placeholders may be null, and transforms have not run. The completed input is validated before the generator finishes; parser, source-stream, and final ZodError failures propagate to the consumer.

OpenAI structured outputs

import { withResponseModel } from "zod-stream"
 
const params = withResponseModel({
  response_model: {
    schema,
    name: "Extract_details",
    description: "Extract the requested details"
  },
  mode: "JSON_SCHEMA",
  params: {
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "Extract this..." }]
  }
})

JSON_SCHEMA uses OpenAI's current structured-output payload:

{
  response_format: {
    type: "json_schema",
    json_schema: { name, description, schema, strict: true }
  }
}

The schema comes from Zod 4's native z.toJSONSchema input conversion. Object schemas are recursively closed for OpenAI strict mode. Unrepresentable Zod types throw during parameter construction, and schemas must still fit OpenAI's supported JSON Schema subset.

Response modes

Prefer JSON_SCHEMA or TOOLS. The legacy modes remain explicit compatibility surfaces and are not silently redirected.

Migration from 3.x

1. Upgrade to Zod 4 and OpenAI 6.
2. Remove zod-to-json-schema.
3. Treat streamed values as ZodStreamChunk<T>, not Partial<z.output<T>>.
4. Update JSON_SCHEMA middleware and snapshots for type: "json_schema".
5. Pass an explicit client to createAgent and handle final validation errors.