<!-- BusyBot node reference — https://busybot.net/tools/openai-structured-output/ -->

> Node: OpenAI Structured Output (`openai_structured_output`) · Action · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/openai/) 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.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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.