OpenAI Structured Output

Get structured JSON responses from OpenAI with schema enforcement.

Overview

Sends a user message to the OpenAI Responses API (POST /responses) with a JSON Schema definition, forcing the model to return structured JSON that conforms to the schema. Uses the Structured Outputs feature (json_schema response format with strict mode). Each input item produces one API call. The parsed JSON object is placed in a configurable output field (default: “structured”) along with model name and token usage metadata.

Category: AI
Tool Name: openai_structured_output
Version: 1

Appearance: Icon: openai | Color: #10a37f

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires OpenAI credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Model	options	No	(current default)	The OpenAI model to use for structured output generation. Always uses the latest version (auto-updated).
				Options: the OpenAI chat models available to your workspace — pick one from the dropdown.
System Prompt	string	No	—	System instructions that guide the model on how to extract or generate the structured data. Leave empty for default behavior. Supports expressions.
User Message	string	Yes	—	The user message or text to process. If empty, falls back to item.json.message or item.json.prompt. Supports expressions.
Attachment File ID	string	No	—	Optional OpenAI file ID (file-…) returned by openai_file_upload. When provided, the file is attached as a content block on the user message — the model will extract structured output from the file content. Falls back to item.json.attachmentFileId if empty. Supports expressions like {{ $json.fileId }} from an upstream openai_file_upload node.
Attachment Type	options	No	document	How the model should interpret the attached file. Only used when Attachment File ID is set.
				Options: document (PDF / text / code / CSV / structured file), image (jpg / png / gif / webp)
JSON Schema	json	Yes	{ "type": "object", "properties": { "result": { "type": "string" } }, "required": ["result"], "additionalProperties": false }	JSON Schema definition that the model output must conform to. For strict mode, include “additionalProperties”: false at each object level. Supports expressions.
Options	collection	No	{}	Optional generation settings — add only the fields you need.
— Temperature	number	No	1	Sampling temperature (0-2). Lower values make output more focused and deterministic. Use 0 for most consistent structured extraction.
— Max Output Tokens	number	No	4096	Maximum number of tokens the model can generate in the response.
— Strict	boolean	No	true	Whether to enforce strict schema adherence. When true, the model is guaranteed to output valid JSON matching the schema exactly.
— Response Field Name	string	No	structured	Field name in the output JSON where the parsed structured response will be placed.
Include Input	boolean	No	false	Whether to include the original input item fields in the output alongside the structured response.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item. The parsed object lands on the field named by Response Field Name (structured by default), with model and usage beside it. The rest of the input item JSON is dropped unless Include Input is on; binary data on the input item is forwarded unchanged.

{
  "structured": { "name": "Ada Lovelace", "email": "ada@example.com" },
  "model": "the model that produced the response",
  "usage": { "input_tokens": 310, "output_tokens": 48 }
}

• The shape inside the response field is whatever your JSON Schema defines — address it directly downstream, e.g. {{ $json.structured.email }}.
• If the model’s reply cannot be parsed as JSON, the field holds { "_raw": "...", "_parseError": "..." } instead. Branch on _parseError when you need to catch that case.

Usage Examples

• Extract contact information from unstructured text into a JSON object
• Classify customer feedback into predefined categories with confidence scores
• Parse invoices into structured line items with amounts and descriptions
• Convert natural language descriptions into structured product attributes
• Extract entities (people, places, dates) from text in a consistent schema

Example Configuration

Extract contact details into a fixed schema:

{
  "type": "openai_structured_output",
  "parameters": {
    "systemPrompt": "Extract the requested fields. Use null when a field is absent.",
    "userMessage": "{{ $json.rawText }}",
    "jsonSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\" },\n    \"email\": { \"type\": \"string\" }\n  },\n  \"required\": [\"name\", \"email\"],\n  \"additionalProperties\": false\n}",
    "options": {
      "temperature": 0,
      "responseFieldName": "contact"
    }
  }
}

Classify feedback at volume, keeping the original item fields:

{
  "type": "openai_structured_output",
  "parameters": {
    "systemPrompt": "Classify the feedback and score your confidence from 0 to 1.",
    "userMessage": "{{ $json.feedback }}",
    "jsonSchema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"category\": { \"type\": \"string\" },\n    \"confidence\": { \"type\": \"number\" }\n  },\n  \"required\": [\"category\", \"confidence\"],\n  \"additionalProperties\": false\n}",
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxOutputTokens": 256,
      "strict": true
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

This tool sends a user message to the OpenAI Responses API with a JSON Schema definition, enforcing strict-mode structured output. Use it when downstream workflow nodes require typed, predictable data rather than free-form text, such as for entity extraction, classification, or structured form parsing. Each input item produces one API call, placing a parsed JSON object into a configurable output field alongside the model name and token usage metadata.