Advanced Features

Structured Output and JSON Mode

Force Gemini to return valid, typed JSON using response_mime_type and response_schema for reliable data extraction.

Structured Output

Structured output forces Gemini to return valid JSON matching your defined schema. This is essential for applications that need to parse and process model output programmatically.

Two Approaches

Approach 1: response_mime_type only

Set response_mime_type: "application/json" and describe the schema in your prompt. Gemini will return JSON but without strict schema enforcement.

Approach 2: response_schema (recommended)

Provide a full JSON schema. Gemini will strictly follow the schema including required fields, types, and nested structures.

When to Use Structured Output

  • Extracting structured data from unstructured text (receipts, reviews, documents)
  • Classification tasks that return a fixed set of labels
  • Data transformation pipelines
  • Any workflow where your code needs to reliably parse the response

Schema Definition

The schema uses a subset of JSON Schema. Supported types: STRING, NUMBER, INTEGER, BOOLEAN, ARRAY, OBJECT.

Enum Values

Use enums to restrict a field to a fixed set of values — excellent for classification:

typescript
sentiment: {
  type: SchemaType.STRING,
  enum: ["positive", "neutral", "negative"],
}

Using Zod for Schemas

In TypeScript projects, define your schema with Zod and convert it for Gemini. This gives you type safety and a single source of truth for the shape.

Example

typescript
import { GoogleGenerativeAI, SchemaType } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);

// Define a strict response schema
const model = genAI.getGenerativeModel({
  model: "gemini-1.5-pro",
  generationConfig: {
    responseMimeType: "application/json",
    responseSchema: {
      type: SchemaType.OBJECT,
      properties: {
        sentiment: {
          type: SchemaType.STRING,
          enum: ["positive", "neutral", "negative"],
          description: "Overall sentiment of the review",
        },
        score: {
          type: SchemaType.NUMBER,
          description: "Sentiment score from 1-10",
        },
        topics: {
          type: SchemaType.ARRAY,
          items: { type: SchemaType.STRING },
          description: "Main topics mentioned in the review",
        },
        summary: {
          type: SchemaType.STRING,
          description: "One-sentence summary of the review",
        },
      },
      required: ["sentiment", "score", "topics", "summary"],
    },
  },
});

// Analyze a product review
const review = `
  The Gemini 1.5 Pro API is genuinely impressive for long-document tasks.
  The 1M context window is a real differentiator. The pricing is fair but
  the cold start latency can be frustrating during development.
`;

const result = await model.generateContent(`Analyze this review: ${review}`);
const analysis = JSON.parse(result.response.text());

console.log(analysis);
// {
//   sentiment: "positive",
//   score: 7.5,
//   topics: ["long-context", "pricing", "latency", "development experience"],
//   summary: "Positive review highlighting the 1M context window advantage..."
// }
Try it yourself — TYPESCRIPT