Workflow:Openai Openai node Structured Output Parsing
| Knowledge Sources | |
|---|---|
| Domains | LLMs, Structured_Data, Schema_Validation |
| Last Updated | 2026-02-15 12:00 GMT |
Overview
End-to-end process for extracting structured, schema-validated data from OpenAI language models using Zod schemas and the SDK's auto-parsing helpers.
Description
This workflow enables developers to receive type-safe, structured responses from language models instead of free-form text. It uses Zod schemas (v3 or v4) to define the expected output structure, which the SDK converts to JSON Schema and passes to OpenAI's Structured Outputs feature. The model is constrained to produce valid JSON matching the schema, and the SDK automatically parses and validates the response. This works with both the Chat Completions API (via chat.completions.parse()) and the Responses API (via responses.parse()). Streaming structured outputs are also supported, with partial JSON parsed incrementally.
Usage
Execute this workflow when you need the model to return data in a specific, predictable format rather than free-form text. Common use cases include extracting entities from text, generating structured reports, producing API-compatible JSON objects, building UI component trees, and any scenario where downstream code requires typed data. This approach eliminates the need for manual JSON parsing and post-processing validation.
Execution Steps
Step 1: Schema Definition
Define the expected output structure using Zod schemas. Create Zod objects that describe the shape of the data you want the model to return. Zod provides type inference so your parsed response is automatically typed in TypeScript.
Key considerations:
- Use z.object(), z.array(), z.string(), z.number(), z.enum() etc. to build the schema
- Nest schemas for complex structures (e.g., an array of step objects)
- Both Zod v3 and Zod v4 are supported
- The SDK uses a vendored zod-to-json-schema converter internally
Step 2: Response Format Configuration
Wrap the Zod schema with the appropriate SDK helper to create a response format object. For Chat Completions, use zodResponseFormat(). For Responses API, use zodTextFormat(). These helpers convert the Zod schema to JSON Schema and attach it as the response format constraint.
Key considerations:
- zodResponseFormat(schema, name) is for Chat Completions API
- zodTextFormat(schema, name) is for Responses API
- The name parameter gives the schema a label for the API
- The SDK transforms schemas to OpenAI's "strict" JSON Schema subset automatically
Step 3: Parsed API Call
Invoke the parsing endpoint instead of the regular creation endpoint. For Chat Completions, call client.chat.completions.parse() with the response format. For Responses, call client.responses.parse() with a text.format parameter. These methods return responses with an additional parsed field containing the typed data.
What happens:
- The request is sent with response_format (Chat Completions) or text.format (Responses) set
- The model generates JSON constrained to match the provided schema
- The SDK parses the JSON response and validates it against the Zod schema
- The result includes both raw text and the parsed, typed object
Step 4: Parsed Output Consumption
Access the structured data from the response's parsed property. For Chat Completions, read message.parsed. For Responses, read response.output_parsed. The data is fully typed according to your Zod schema, enabling direct use in application logic without additional parsing.
Key considerations:
- Check for refusal before accessing parsed content (model may refuse)
- The parsed object matches your Zod schema's inferred TypeScript type
- For streaming, partial structured output is available via the partial-json-parser