Why it matters
A model returns text that may or may not match the shape the prompt asked for, and the compiler cannot check it. Code that casts parsed JSON to an interface compiles cleanly and fails at the first missing field, usually in front of a user. The useful pattern treats the model boundary like any other external API: parse with a runtime schema, narrow the result, and represent partial and failed states in the type system so callers must handle them.
Mental model
It is a customs declaration: the form says what is inside, and the officer still opens the box. The analogy breaks because a type assertion is a declaration with no officer, which is why the validation step cannot be skipped.
How it works
- 1Define a runtime schema for every model output the application consumes, and parse before use.
- 2Infer the TypeScript type from the schema so a field change updates both at once.
- 3Model streaming as a discriminated union of deltas, tool calls, usage and completion, and handle every variant.
- 4Represent tool arguments as parsed values with an explicit failure case, not as a string that is cast later.
- 5Type the provider client behind an internal interface, so a provider swap does not change application types.
- 6Add a test that feeds malformed and truncated output through the parser and asserts a typed error.
Step 1 of 6
Define a runtime schema for every model output the application consumes, and parse before use.
Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.
What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.
Text version
The page's steps: 1. Define a runtime schema for every model output the application consumes, and parse before… 2. Infer the TypeScript type from the schema so a field change updates both at once. 3. Model streaming as a discriminated union of deltas, tool calls, usage and completion, and… 4. Represent tool arguments as parsed values with an explicit failure case, not as a string … 5. Type the provider client behind an internal interface, so a provider swap does not change… 6. Add a test that feeds malformed and truncated output through the parser and asserts a typ…
- Define a runtime schema for every model output the application consumes, and parse before use.
- Infer the TypeScript type from the schema so a field change updates both at once.
- Model streaming as a discriminated union of deltas, tool calls, usage and completion, and handle every variant.
- Represent tool arguments as parsed values with an explicit failure case, not as a string that is cast later.
- Type the provider client behind an internal interface, so a provider swap does not change application types.
- Add a test that feeds malformed and truncated output through the parser and asserts a typed error.
Trade-offs
| Choice | Good for | Cost | Fails when |
|---|---|---|---|
| Runtime validation at the boundary | Safe against malformed output | Parsing cost and schema maintenance | The payload is large and hot |
| Type assertion | No runtime cost | Failures appear far from the cause | The data crosses a system boundary |
| Strict schema with no optional fields | Clear contract | Model output fails on minor omissions | The model is unreliable on format |
| Lenient parsing with repair | Higher success rate | Silent wrong values | The field carries a decision |
Good for
Safe against malformed output
Cost
Parsing cost and schema maintenance
Fails when
The payload is large and hot
- The payload is large and hot
- The data crosses a system boundary
- The model is unreliable on format
- The field carries a decision
Figure. Each choice with what it buys, what it costs, and the case where it loses.
What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.
Text version
Four trade-offs: Runtime validation at the boundary is good for Safe against malformed output, costs Parsing cost and schema maintenance, and fails when The payload is large and hot. Type assertion is good for No runtime cost, costs Failures appear far from the cause, and fails when The data crosses a system boundary. Strict schema with no optional fields is good for Clear contract, costs Model output fails on minor omissions, and fails when The model is unreliable on format. Lenient parsing with repair is good for Higher success rate, costs Silent wrong values, and fails when The field carries a decision
Failure modes
- Cast instead of parse. A missing field becomes undefined and the failure surfaces in rendering. Debug: feed a response with the field removed through the handler and confirm it fails at the boundary.
- Unhandled stream variant. A new event type arrives and the consumer ignores it, so content is dropped. Debug: log unknown event types and make the union exhaustive with a compile-time check.
- Schema and type drift. The interface is edited but the validator is not, and validation passes the wrong shape. Debug: derive the type from the schema and remove hand-written duplicates.
In production
Log validation failures with the model, prompt version and a redacted sample, and alert on a rising rate, since it usually means a prompt or provider change. Cap retries on invalid output so a formatting problem cannot become a cost problem.
Common misconceptions
People think: TypeScript types protect against bad model output.
Actually: Types are erased at runtime; only validation at the boundary protects the program.
People think: Structured output mode removes the need to validate.
Actually: It raises conformance, and the response is still external input that can be truncated, refused or shaped unexpectedly.
Interview angle
Put validation at the boundary, derive the type from the schema and model streaming as a union. Mention exhaustive handling. Casting the parsed response and trusting the prompt is the mistake.
Sources
- TypeScript Handbook — narrowing, discriminated unions and type inference.
- Zod documentation — runtime schema validation with inferred types.
- OpenAI, Structured outputs — schema-constrained generation and its limits.