Gemini Structured Output & JSON Mode: Reliable Data Extraction
Master Gemini's structured output capabilities. Learn JSON schema enforcement, prompt patterns for reliable extraction, handling nested objects, and common schema design antipatterns.
Getting structured data out of LLMs reliably is hard. Without constraints, Gemini will occasionally deviate from your requested format — wrapping JSON in markdown fences, adding commentary, using inconsistent field names, or hallucinating fields that don't exist in your schema.
Gemini's structured output mode, combined with response_schema or response_mime_type configuration, addresses this at the API level. But prompting still matters enormously — schema enforcement prevents malformed output, but good prompting determines whether the extracted data is actually correct.
Enabling Structured Output
JSON Mode (response_mime_type)
{
"generationConfig": {
"responseMimeType": "application/json"
}
}
This ensures Gemini returns valid JSON with no markdown wrapping, no commentary, no explanatory text. But it doesn't enforce a specific schema — the JSON structure is whatever Gemini generates.
Schema Enforcement (response_schema)
{
"generationConfig": {
"responseMimeType": "application/json",
"responseSchema": {
"type": "OBJECT",
"properties": {
"products": {
"type": "ARRAY",
"items": {
"type": "OBJECT",
"properties": {
"name": { "type": "STRING" },
"price": { "type": "NUMBER" },
"in_stock": { "type": "BOOLEAN" },
"categories": {
"type": "ARRAY",
"items": { "type": "STRING" }
}
},
"required": ["name", "price", "in_stock"]
}
}
},
"required": ["products"]
}
}
}
This enforces the schema at the API level — Gemini cannot return a response that doesn't match the specified structure. Missing required fields or wrong types will cause the API to reject the output.
Note:
Schema enforcement doesn't guarantee the data is correct — only that it's well-formed. Gemini can fill price: 999999 into a required number field without the price being accurate. Always validate extracted data against source material.
Prompting for Reliable Extraction
Schema enforcement solves formatting. The prompt solves accuracy.
The Extraction Prompt Pattern
Extract the following information from the provided [DOCUMENT/IMAGE/TEXT].
OUTPUT SCHEMA:
[Describe your schema in plain language alongside the formal schema]
EXTRACTION RULES:
1. If a field's value is not present in the source, use null — never
fabricate data to fill required fields
2. For numeric fields: extract exactly what's stated. Do not convert
units or perform calculations unless explicitly instructed
3. For boolean fields: only return true if the source explicitly
states or unambiguously shows the condition. Default to false
4. For text fields: extract verbatim, not paraphrased
5. If you're uncertain about any value, include a confidence field:
{ "value": ..., "confidence": "high|medium|low" }
SOURCE:
[Your content to extract from]
Example: Extracting from Unstructured Text
Extract structured data from the following product descriptions.
SCHEMA (for each product):
{
"name": string, // Product name exactly as written
"price": number, // Numeric price only (no currency symbol)
"currency": string, // USD, EUR, GBP, etc.
"features": string[], // Distinct features mentioned
"warranty_years": number | null // Warranty duration if mentioned
}
RULES:
- If multiple prices appear (sale, MSRP), extract all as an array
- Features should be individual, distinct items — not comma-separated
strings
- If no warranty is mentioned, use null (not 0)
PRODUCT DESCRIPTIONS:
[Your text]
Schema Design Best Practices
| Do | Don't |
|---|---|
Use null for missing data | Use 0 or "" as sentinel for missing |
| Keep nesting ≤ 3 levels deep | Deeply nest objects (Gemini accuracy drops past 3-4 levels) |
| Use arrays of objects for lists | Use comma-separated strings inside a single field |
Include required field lists | Leave all fields optional (you'll get inconsistent output) |
| Add confidence fields for ambiguous extraction | Assume extraction is always certain |
| Use enums for constrained values | Use free-text for fields with a known set of values |
Enum Pattern
{
"sentiment": {
"type": "STRING",
"enum": ["positive", "negative", "neutral", "mixed"]
}
}
Enums produce far more consistent results than free-text fields for categorical data. Gemini is less likely to return "somewhat positive" or "mostly good" when those aren't valid enum values.
Handling Ambiguity
For fields where extraction might legitimately be uncertain:
{
"extracted_name": {
"type": "OBJECT",
"properties": {
"value": { "type": "STRING" },
"confidence": {
"type": "STRING",
"enum": ["high", "medium", "low"]
},
"evidence": { "type": "STRING" }
}
}
}
The evidence field forces Gemini to point to where in the source it found the information, which reduces hallucination.
Nested Object Extraction
For complex documents, flatten where possible:
// HARD for Gemini (deeply nested, implicit relationships)
{
"company": {
"departments": [
{
"name": "...",
"employees": [
{
"name": "...",
"manager": { "name": "..." } // Object reference
}
]
}
]
}
}
// EASIER for Gemini (flattened, explicit relationships)
{
"departments": [
{ "id": "dept-1", "name": "Engineering" }
],
"employees": [
{
"name": "Alice Chen",
"department_id": "dept-1",
"manager_name": "Bob Smith"
}
]
}
Note:
Deeply nested schemas with object references (where one extracted entity references another by ID) are the most common cause of schema extraction failures. Gemini loses track of cross-references in complex hierarchies. Flatten to arrays with explicit foreign keys whenever possible.
Common Schema Antipatterns
| Antipattern | Problem | Fix |
|---|---|---|
| Overly permissive types | "type": "STRING" for everything | Use specific types, enums, and constraints |
Missing required array | Gemini omits fields unpredictably | Always specify required for critical fields |
| Deep nesting | Accuracy decays past 3 levels | Flatten with explicit IDs |
| No null handling | Required fields force fabrication | Allow null for fields that may be absent |
| Vague field descriptions | Gemini guesses what you want | Add description to every schema property |
| Too many fields | Accuracy per field drops past ~15 fields | Break into multiple extraction passes |
Multi-Pass Extraction
For documents with 15+ fields, split extraction into passes:
// PASS 1: Extract entity list
Extract all product names and IDs from this catalog.
Schema: { products: [{ id: string, name: string }] }
// PASS 2: Extract details per entity
For each product from Pass 1, extract:
Schema: { details: [{ id: string, price: number, ... }] }
// PASS 3: Merge (application-side, not Gemini)
Merge details into products by matching IDs.
This is more API calls but produces more accurate results than a single massive extraction pass.
Common Failures
| Failure | Cause | Fix |
|---|---|---|
| Fabricated values | Required field with no data in source | Allow null; add explicit "use null if not found" rule |
| Type mismatches | Gemini returns "N/A" for a number field | Schema enforcement catches this; add extraction rules |
| Inconsistent enums | Free-text fields for categorical data | Use enum constraints |
| Missing nested fields | Deep nesting confuses extraction | Flatten to ≤ 3 levels |
| Commentary in output | Gemini adds explanations | Use responseMimeType: "application/json" to suppress |
Related Pages
- Function Calling — Structured output for tool use
- Streaming & Real-time — Streaming structured output
Related Articles
Westerns & Frontier Cinematic SREF Codes
Midjourney SREF codes for wide open landscapes with dusty, sun-baked western and frontier aesthetics.
Data & Analytics: ChatGPT Prompts for Analysts
A curated collection of ChatGPT prompts for data analysts — SQL, data cleaning, visualization, statistical analysis, storytelling, and more.
Exam Preparation Guide: ChatGPT Prompts for Success
Master exam preparation with these ChatGPT prompts designed to help you study effectively, create study schedules, and perform well in academic assessments.