Gemini Structured Output

Get structured JSON responses with Gemini schema enforcement.

Overview

Gemini Structured Output sends a message to a Google Gemini model with a JSON schema attached, forcing the model to answer with valid JSON that matches that schema. The schema is applied at generation time, so downstream nodes get predictable, typed data instead of free-form text that has to be parsed. The parsed object is written to a configurable field on the output item, together with the model name and token usage. Optional file references can be sent as multimodal context alongside the message.

Category: AI
Tool Name: gemini_structured_output
Version: 1

Appearance: Icon: gemini | Color: #ffffff

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

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

Parameters

Parameter	Type	Required	Default	Description
Model	options	No	—	The Gemini model to use for structured output generation. Pick a specific version — labels are pinned, not aliased to “latest”. The dropdown lists the models currently available for this node; leave it unset to use the default.
System Prompt	string	No	—	Optional system instruction that sets the behavior and context for the model. Supports expressions.
User Message	string	Yes	—	The message to send to the Gemini model. Falls back to item.message or item.prompt if empty. Supports expressions.
File URIs	string	No	—	Optional. fileUri value(s) from the Gemini File Upload tool. Pass a single URI or a JSON array for multiple files. Files are sent as multimodal context alongside the message. Falls back to item.fileUris if empty. Gemini File API retains uploads for 48 hours.
JSON Schema	json	Yes	{}	The JSON Schema that the model response must conform to. Passed as generationConfig.responseSchema. Can be a JSON object or a string that will be parsed.
Options	collection	No	{}	Optional tuning for the generation request.
— Temperature	number	No	1	Controls randomness. Lower values are more deterministic, higher values are more creative. Range: 0-2.
— Max Output Tokens	number	No	8192	Maximum number of tokens in the generated response.
— Response Field Name	string	No	structured	The key name in the output JSON where the parsed structured response will be stored.
Include Input	boolean	No	false	Whether to merge the input item JSON into the output item.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item. Binary data arriving from upstream is forwarded untouched.

The output item’s JSON contains only the fields below. The input item’s JSON is merged in only when Include Input is on:

Field	Description
structured	The parsed object the model returned, shaped by your JSON Schema. Renamed by Response Field Name.
model	The model that produced the response.
usage	Token usage metadata reported by the model.

If the response cannot be parsed as JSON, the response field holds _raw (the raw text) and _parseError (why parsing failed) instead of your schema’s keys — worth guarding for in a downstream branch if the workflow must not silently continue.

Reference the result downstream by expression, e.g. {{ $json.structured.category }}.

Usage Examples

• Extract structured data from unstructured text using a JSON schema
• Parse entities from a document into a defined JSON format
• Generate structured product descriptions matching a schema
• Convert free-text responses into typed JSON objects
• Use Gemini to classify items and return results in a fixed schema

Example Configuration

Minimal — a message and the schema it must satisfy:

{
  "type": "gemini_structured_output",
  "parameters": {
    "userMessage": "Extract the key facts from the following text: {{ $json.text }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "facts": {
          "type": "array",
          "items": { "type": "string" }
        }
      },
      "required": ["facts"]
    }
  }
}

Ticket triage with a system prompt, a renamed output field and the source data kept:

{
  "type": "gemini_structured_output",
  "parameters": {
    "systemPrompt": "You are a precise data extraction assistant. Return only factual information present in the source text. Do not infer or hallucinate.",
    "userMessage": "Analyze the following customer support ticket and extract structured data:\n\n{{ $json.ticketBody }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "category": { "type": "string", "enum": ["billing", "technical", "account", "other"] },
        "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
        "issueDescription": { "type": "string" },
        "suggestedActions": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["category", "priority", "issueDescription", "suggestedActions"]
    },
    "includeInput": true,
    "maxConcurrency": 5,
    "options": {
      "temperature": 0.2,
      "maxOutputTokens": 1024,
      "responseFieldName": "ticketData"
    }
  }
}

Batch classification at temperature 0 for consistent labels:

{
  "type": "gemini_structured_output",
  "parameters": {
    "userMessage": "Classify this product description into a single category: {{ $json.description }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "category": { "type": "string", "enum": ["electronics", "clothing", "food", "furniture", "other"] },
        "confidence": { "type": "number" }
      },
      "required": ["category", "confidence"]
    },
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxOutputTokens": 256,
      "responseFieldName": "classification"
    }
  }
}

Analyze an uploaded file by passing its URI from the Gemini File Upload node:

{
  "type": "gemini_structured_output",
  "parameters": {
    "userMessage": "Extract the invoice number, total and due date from the attached document.",
    "fileUris": "{{ $json.fileUri }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "invoiceNumber": { "type": "string" },
        "total": { "type": "number" },
        "dueDate": { "type": "string" }
      },
      "required": ["invoiceNumber", "total"]
    }
  }
}

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

Gemini Structured Output sends a user message to the Google Gemini generateContent API with a strict JSON schema constraint, forcing the model to return syntactically valid, schema-conformant JSON. Use it when downstream workflow nodes require predictable, typed data structures rather than free-form text, such as extracting entities, classifying inputs, or populating structured records. It produces a parsed JSON object matching your schema, the model name used, and token usage metadata containing prompt and completion counts.