Structured JSON Outputs with Gemini API Schema Controls

The JSON Parsing Challenge in LLMs

Standard LLM calls are non-deterministic, often returning conversational text or code wrappers (like “`json) along with requested data. When integrating these outputs into automated backend workflows, parsing errors are common.

Case Study: AI Content Generator Failures

A background worker was designed to generate blog posts via AI and save them to a database. Every 10th run, the worker failed because the model included extra remarks like “Here is the post you requested:” which threw JSON parse exceptions.

The Bug: Fragile String Extraction

The developer tried to clean up conversational text using regex and string splits:

// Fragile parsing
$json_str = str_replace("```json", "", $response);
$json_str = str_replace("```", "", $json_str);
$data = json_decode($json_str);

If the model changed its wording or returned partial markdown, this parser broke immediately.

The Fix: Gemini responseSchema Configuration

We configured the Gemini API to return structured JSON by specifying a strict JSON Schema directly in the API payload:

$payload = [
    'contents' => [['parts' => [['text' => $prompt]]]],
    'generationConfig' => [
        'responseMimeType' => 'application/json',
        'responseSchema' => [
            'type' => 'OBJECT',
            'properties' => [
                'title' => ['type' => 'STRING'],
                'body' => ['type' => 'STRING'],
                'tags' => [
                    'type' => 'ARRAY',
                    'items' => ['type' => 'STRING']
                ]
            ],
            'required' => ['title', 'body', 'tags']
        ]
    ]
];

This forced the Gemini engine to structure its output to match the schema, eliminating parsing exceptions completely.