Structured output for TypeScript LLM apps

Zod in, typed data out.

Define the expected shape with Zod. zodstructor turns free-form model output into validated, strongly typed data — with provider-native structured output, tool calling, and two independent retry layers.

Get started Try the live demo

0providers

0output modes

0retry layers

MITlicense

quickstart.ts

01Why zodstructor

Everything between the model and your types

A thin, testable layer that turns probabilistic text into deterministic data.

Schema-first types

z.infer flows from the Zod schema straight into the resolved value. One source of truth, zero hand-written interfaces.

Five output modes

json_schema, tool_call, json_object, prompt, or auto — pick the strongest guarantee each provider actually supports.

Two retry layers

Validation retries feed Zod issues back to the model for self-repair; transport retries back off independently on network failures.

Streaming + partial previews

Stream raw text as it arrives, render best-effort partial previews, and still finish with full schema validation.

Provider-native

OpenAI chat.completions, OpenAI Responses, OpenAI-compatible gateways, Anthropic, and Google Gemini.

Strict schema generation

Optional, default and catch fields become anyOf [T, null] in strict object mode — no silent schema drift.

02Output modes

Pick the guarantee, not the prayer

Each mode trades compatibility against enforcement strength. Explicit beats auto.

Mode	Behavior	Best for
`json_schema`	Provider-native schema enforcement where available	Highest guarantee on OpenAI structured output
`tool_call`	Function / tool calling; arguments validated as JSON	Tool-native models and agent workflows
`json_object`	JSON-only response without native schema enforcement	Compatible gateways with JSON mode
`prompt`	Prompt injection only	Legacy or limited OpenAI-compatible endpoints
`auto`	Backward-compatible default; prefer explicit modes in new code	Migration path

03Install

Up and running in two commands

Install the core, then only the provider SDKs you actually use.

Core library

zodstructor plus its peer, zod.

npm install zodstructor zod

Provider SDKs — pick yours

Each provider is an optional peer dependency.

npm install openai

npm install @anthropic-ai/sdk

npm install @google/generative-ai

Verify

Import the client and run your first completion.

npx tsc --noEmit && npm test

quickstart.ts

04Live demo

Watch free text become typed data

A simulated run of the real pipeline: request → streamed raw text → Zod validation → typed value.

Scenario

Output mode

Model input

Zod schema

Raw stream idle

Zod validation passed

05Retries & streaming

Failures are inputs, not exceptions

Validation retries feed Zod issues back to the model so it can repair its own output. Transport retries use exponential backoff for network and HTTP failures — independently tunable.

During streaming, partial previews close unterminated strings and brackets without ever inventing fields; the final value still goes through full schema validation.

maxRetries — validation repair attempts
transportRetries — network/HTTP attempts
retryDelayMs — exponential backoff base
partialSchema — best-effort live previews

streaming.ts

06Documentation

Read the module docs

Every subsystem has its own deep-dive, in English and Chinese.

Core client & retry engine

The completion pipeline, validation repair loop, and transport backoff.

Zod → JSON Schema

Strict schema generation, anyOf nullables, and provider quirks.

Providers & compatibility

OpenAI, Responses API, Anthropic, Gemini, and compatible gateways.

Streaming & partial previews

Truncated-JSON repair and how final validation stays authoritative.

Testing strategy

Unit coverage plus the real-provider integration matrix.

Design notes

The trade-offs and invariants behind the public API.

07FAQ

Frequently asked questions

Straight answers about what zodstructor does and how it works.

What is zodstructor?

zodstructor is an open-source TypeScript library for structured LLM output. You define the expected shape with a Zod schema, and it converts free-form model output into validated, strongly typed data whose TypeScript type is inferred directly from the schema.

Which LLM providers are supported?

Five: OpenAI chat.completions, the OpenAI Responses API, OpenAI-compatible gateways, Anthropic, and Google Gemini. Each provider SDK is an optional peer dependency, so you only install what you use.

How do the two retry layers work?

Validation retries feed Zod issues back to the model so it can repair its own output (maxRetries). Transport retries handle network and HTTP failures independently with exponential backoff (transportRetries, retryDelayMs). The two layers are configured and counted separately.

What is the difference between json_schema and tool_call mode?

json_schema uses provider-native schema enforcement for the strongest guarantee on supported OpenAI endpoints. tool_call routes through function/tool calling and validates the tool arguments as JSON, which suits tool-native models and agent workflows. json_object and prompt are weaker modes for compatible or legacy gateways.

Does zodstructor support streaming?

Yes. streamStructured yields raw text as it arrives and can emit best-effort partial previews through partialSchema — the preview only closes unterminated strings and brackets and never invents fields. The final value always goes through full Zod validation.

Is zodstructor production ready? What is the license?

zodstructor is in beta: the core path is tested and buildable, and real-provider compatibility should be gated by the integration matrix before production rollout. It is MIT licensed and free to use.

Stop parsing. Start validating.

One Zod schema. Typed data, every time.

Install zodstructor Star on GitHub