This is a community node for n8n that enables you to extract structured JSON from unstructured text by leveraging OpenAI’s Structured Outputs feature with a user‑provided JSON Schema.
You can install n8n-nodes-openai-structured-outputs in two ways—via npm or directly from the n8n app.
-
In your project (or globally), run:
npm install n8n-nodes-openai-structured-outputs
-
Restart your n8n instance to load the new node.
Note: Only the n8n instance owner can install and manage community nodes.
- In n8n, go to Settings → Community Nodes.
- Click Install.
- Click Browse—n8n will show npm packages tagged
n8n-community-node-package
. - Search for and select n8n-nodes-openai-structured-outputs.
- To install a specific version, append
@<version>
(e.g.n8n-nodes-openai-structured-outputs@*.*.*
).
- To install a specific version, append
- Check “I understand the risks of installing unverified code from a public source”, then click Install.
- After installation, the OpenAI Structured Output node appears under Community Nodes → Utility.
- Uninstall: In Settings → Community Nodes, click the three-dot menu next to OpenAI Structured Output and choose Uninstall.
- Upgrade to Latest: If a new version is available, an Update button appears next to the node—click it to upgrade.
-
Install Specific Version: Uninstall first, then reinstall using the exact npm package name with version (e.g.
n8n-nodes-openai-structured-outputs@*.*.*
). - Downgrade: Same as installing a specific older version.
For full details and additional community-node management guidance, see the official docs:
https://docs.n8n.io/integrations/community-nodes/installation/
Use the Extract JSON operation to send text to the OpenAI Chat Completions endpoint with your JSON Schema injected into response_format
. The node will:
-
Call
POST /v1/chat/completions
with:-
model
(selectable) -
messages
: system prompt + user text -
response_format
:{ type: "json_schema", json_schema: { name, schema, strict: true } }
- optional parameters like
temperature
-
-
Receive the AI’s response, automatically:
-
Validate HTTP errors (
4xx
/5xx
) -
Parse the first choice’s
message.content
as JSON - Validate the parsed JSON against your schema (using AJV with coercion, defaults, and stripping extra fields)
-
Output:
-
Validate HTTP errors (
Parameter | Name | Type | Default | Description |
---|---|---|---|---|
Model | model |
options | gpt-4o |
OpenAI model to use (e.g. gpt-4o-mini , o3-mini , etc.) |
JSON Schema | jsonSchema |
json | "" |
A valid JSON Schema (injected into response_format ) |
Text | text |
string | "" |
Input text from which to extract structured data |
Temperature | temperature |
number | 1 |
Sampling temperature (0–1) |
This node uses the built‑in OpenAI API
credential:
- API Key (required)
- Organization ID (optional)
-
Base URL (defaults to
https://api.openai.com/v1
)
Configure these under Settings → API Credentials → OpenAI in n8n.
- n8n version: ≥ 1.x with Community Nodes API v1
- Node.js: ≥ 18.10
- AJV version: 8.x (bundled)
- Add the OpenAI Structured Output node to your workflow.
- Select Extract JSON.
- Fill in your Model, paste or compose your JSON Schema, and supply the Text.
- Connect an output to inspect:
-
parsed
: the coerced, default‑filled, extra‑fields‑removed object -
errors
: any AJV validation errors
-
You can chain this into further nodes (e.g., write to a database, send an email) knowing the JSON conforms to your schema.
We leverage the industry‑standard JSON Schema draft (see official docs):
https://json-schema.org/understanding-json-schema/
OpenAI’s Structured Outputs supports many common JSON Schema keywords, but also has explicit limitations. Below is a summary of what works (✔) and what does not (✘) for each data type:
- ✔ type
- ✔ enum
- ✔ const
- ✔ contentEncoding (if supported)
- ✔ contentMediaType (if supported)
- ✘ minLength, maxLength, pattern, format
- ✔ type
- ✔ enum
- ✔ const
- ✔ exclusiveMinimum, exclusiveMaximum
- ✘ minimum, maximum, multipleOf
- ✔ type
- ✔ enum
- ✔ const
- ✔ type
- ✔ properties
- ✔ required (mandatory): an array that must list all property names declared under
properties
. - ✔ additionalProperties (mandatory): must be explicitly set (
false
or a subschema) to control extra fields. - ✔ dependencies (if supported)
- ✔ patternDependentSchemas (if supported)
- ✘ patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- ✔ type
- ✔ items
- ✔ additionalItems
- ✔ prefixItems (if supported)
- ✘ unevaluatedItems, contains, minContains, maxContains, minItems, maxItems, uniqueItems
- ✔ enum
- ✔ const
- ✔ anyOf
- ✔ allOf (not explicitly unsupported)
- ✘ oneOf, not (unsupported or untested)
- ✔ if, then, else (if supported)
- ✔ description, title
- ✘ default
- ✘ $ref, $defs/definitions (no external references)
Tip: Schema reuse via
$defs
inside the same document may work, but external$ref
is not supported.
- n8n Community Nodes: https://docs.n8n.io/integrations/community-nodes/
- OpenAI Chat Completions: https://platform.openai.com/docs/guides/chat/introduction
- JSON Schema Official: https://json-schema.org/understanding-json-schema/
-
0.1.0 (2025‑04‑22)
- Initial release: Extract JSON via OpenAI Structured Outputs with full AJV validation, coercion, defaults, and extra‑field removal.
Created by Crucerlabs · MIT License