	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > Gemini Structured Output with JSON Schema

Gemini Structured Output with JSON Schema

Author: Venkata Sudhakar

Gemini structured output lets you define an exact JSON schema that the model must follow when generating its response. Instead of hoping the model returns valid JSON and writing fragile parsing code, you declare the schema upfront and Gemini guarantees the output matches it ï¿½ correct field names, correct types, no extra text, no markdown fences. This is the right approach for any use case where the output feeds into a downstream system: data extraction pipelines, database insertion, API responses, or any business automation workflow that depends on consistent structure.

Structured output is configured via response_schema in GenerateContentConfig. You define the schema using google.genai.types Schema objects or equivalently using Python dataclasses with the typing module. The model returns a JSON string that always matches the schema ï¿½ you can safely call json.loads() without a try/except. Fields can be required or optional, typed as STRING, NUMBER, BOOLEAN, ARRAY, or OBJECT, and nested to any depth. Use response_mime_type of application/json alongside the schema to ensure clean JSON output.

The below example builds a product review extraction pipeline that takes unstructured customer review text and reliably extracts rating, sentiment, product features mentioned, and recommended improvements ï¿½ always as valid structured JSON.

import json
from google import genai
from google.genai import types

client = genai.Client(api_key="your-gemini-api-key")

# Define the exact schema Gemini must return
REVIEW_SCHEMA = types.Schema(
    type=types.Type.OBJECT,
    required=["rating", "sentiment", "summary", "pros", "cons", "recommend"],
    properties={
        "rating": types.Schema(
            type=types.Type.INTEGER,
            description="Numeric rating out of 5 inferred from the review text"
        ),
        "sentiment": types.Schema(
            type=types.Type.STRING,
            enum=["positive", "neutral", "negative", "mixed"]
        ),
        "summary": types.Schema(
            type=types.Type.STRING,
            description="One sentence summary of the review"
        ),
        "pros": types.Schema(
            type=types.Type.ARRAY,
            items=types.Schema(type=types.Type.STRING),
            description="List of positive aspects mentioned"
        ),
        "cons": types.Schema(
            type=types.Type.ARRAY,
            items=types.Schema(type=types.Type.STRING),
            description="List of negative aspects or complaints mentioned"
        ),
        "recommend": types.Schema(
            type=types.Type.BOOLEAN,
            description="True if the reviewer recommends the product"
        ),
        "product_category": types.Schema(
            type=types.Type.STRING,
            description="Product category inferred from review context"
        )
    }
)

def extract_review(review_text: str) -> dict:
    resp = client.models.generate_content(
        model="gemini-2.0-flash",
        config=types.GenerateContentConfig(
            response_mime_type="application/json",
            response_schema=REVIEW_SCHEMA,
            system_instruction=(
                "Extract structured information from customer product reviews. "
                "Infer the numeric rating from the tone and language if not explicitly stated. "
                "Be precise and conservative with pros and cons."
            ),
            max_output_tokens=400
        ),
        contents=[review_text]
    )
    return json.loads(resp.text)  # always valid JSON - no try/except needed

Extracting structured data from unstructured review text,

reviews = [
    ("The Sony WH-1000XM5 headphones are absolutely brilliant! "
     "The noise cancellation is the best I have ever experienced - "
     "complete silence on my Mumbai metro commute. Battery lasts forever, "
     "well past the 30 hours claimed. Only minor gripe is the case is a bit bulky. "
     "Worth every rupee of the Rs 29,990 price tag. Highly recommend!"),

("Samsung Galaxy Tab A9+ is decent but disappointing for the price. "
     "The display is nice and bright, good for watching videos. "
     "But performance is sluggish when multitasking and 4GB RAM shows its limits. "
     "Gaming is frustrating - frame drops constantly. "
     "For basic use it is okay but do not expect flagship performance."),
]

for review_text in reviews:
    extracted = extract_review(review_text)
    print("Review excerpt:", review_text[:60], "...")
    print("Rating:    ", extracted["rating"], "/ 5")
    print("Sentiment: ", extracted["sentiment"])
    print("Summary:   ", extracted["summary"])
    print("Pros:      ", extracted["pros"])
    print("Cons:      ", extracted["cons"])
    print("Recommend: ", extracted["recommend"])
    print("Category:  ", extracted["product_category"])
    print()

# Batch extraction for database insertion
all_reviews = [extract_review(r) for r in reviews]
print("All", len(all_reviews), "reviews extracted - ready for database insertion")
print("Fields guaranteed present:", list(all_reviews[0].keys()))

It gives the following structured output with guaranteed schema compliance,

Review excerpt: The Sony WH-1000XM5 headphones are absolutely brilliant! ...
Rating:     5 / 5
Sentiment:  positive
Summary:    Exceptional noise-cancelling headphones with outstanding battery life.
Pros:       ["Best-in-class noise cancellation", "30+ hour battery life",
             "Excellent value for Rs 29,990"]
Cons:       ["Bulky carrying case"]
Recommend:  True
Category:   Audio / Headphones

Review excerpt: Samsung Galaxy Tab A9+ is decent but disappointing for the price. ...
Rating:     3 / 5
Sentiment:  mixed
Summary:    A decent tablet for basic use but underperforms for multitasking and gaming.
Pros:       ["Bright and clear display", "Good for video streaming"]
Cons:       ["Sluggish multitasking", "4GB RAM insufficient", "Gaming frame drops"]
Recommend:  False
Category:   Tablets

All 2 reviews extracted - ready for database insertion
Fields guaranteed present: ["rating", "sentiment", "summary", "pros",
                            "cons", "recommend", "product_category"]

# Schema-enforced output: no missing fields, no wrong types, no markdown
# json.loads() called directly with no error handling needed

Structured output use cases: product data extraction from unstructured supplier sheets, customer feedback categorisation at scale, invoice parsing into structured records, document classification pipelines, and any ETL workflow where LLM output feeds directly into a database or API. Always define required fields in the schema ï¿½ optional fields may be omitted by the model. For nested objects, define a full Schema hierarchy rather than using generic OBJECT types. Test your schema against 10 to 20 real examples before production deployment to verify the model produces sensible values for inferred fields like rating and sentiment.

Send your comments, suggestions or queries regarding this site to [email protected].