Structured JSON Responses

What Is Structured Output?

Normal AI output is designed primarily for people to read. Structured output is designed for an application to process.

Instead of asking Gemini to return an unpredictable paragraph, we provide a JSON Schema defining the exact fields and data types the application expects.

Why Plain Text Can Be Difficult

Suppose an application asks Gemini to analyze a customer message. A normal response might be:

This appears to be a moderately urgent follow-up message.
The customer is asking for confirmation that the proposal was
received and would appreciate a response today.

A person can understand that response, but application code must guess where the urgency, message type, summary, and requested action appear.

The wording could also change with every request.

The Structured Version

The same analysis can be returned as:

{
    "message_type": "follow_up",
    "sentiment": "neutral",
    "urgency": "medium",
    "summary": "The sender is following up to confirm receipt of a proposal.",
    "action_items": [
        "Confirm whether the proposal was received",
        "Provide a response today if possible"
    ],
    "recommended_reply": "Thank you for following up. I received the proposal and will review it as soon as possible."
}

PHP and JavaScript can now access each value directly:

$messageType = $result['message_type'];
$urgency = $result['urgency'];
$summary = $result['summary'];

Try the Structured Message Analyzer

Enter a business message below. Gemini will return a JSON object that follows a schema stored on the server.

The JSON Schema

The application does not merely ask Gemini to “return JSON.” It supplies a specific schema:

{
    "type": "object",

    "properties": {
        "message_type": {
            "type": "string",
            "enum": [
                "inquiry",
                "follow_up",
                "complaint",
                "request",
                "confirmation",
                "other"
            ]
        },

        "sentiment": {
            "type": "string",
            "enum": [
                "positive",
                "neutral",
                "negative",
                "mixed"
            ]
        },

        "urgency": {
            "type": "string",
            "enum": [
                "low",
                "medium",
                "high"
            ]
        },

        "summary": {
            "type": "string"
        },

        "action_items": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "maxItems": 5
        },

        "recommended_reply": {
            "type": "string"
        }
    },

    "required": [
        "message_type",
        "sentiment",
        "urgency",
        "summary",
        "action_items",
        "recommended_reply"
    ],

    "additionalProperties": false
}

Understanding the Schema

Object

The top-level result must be a JSON object containing named properties.

Properties

Each property defines one value the application expects.

Type

A type determines whether the value must be text, a number, a boolean, an object, or an array.

Enum

An enum limits a value to an approved list.

"urgency": {
    "type": "string",
    "enum": [
        "low",
        "medium",
        "high"
    ]
}

Gemini cannot return values such as "extremely urgent" or "somewhat important" for that field.

Required

Required properties must appear in the returned JSON object.

Additional Properties

Setting additionalProperties to false prevents unplanned fields from being added.

The Response Format

The schema is placed inside the current Interactions API response format:

"response_format": {
    "type": "text",
    "mime_type": "application/json",
    "schema": {
        "type": "object",
        "properties": {
            ...
        }
    }
}

The response is still delivered as text, but that text contains JSON matching the supplied schema.

Valid JSON Is Not Enough

The server performs a second validation after Gemini responds.

It verifies that:

• The response can be decoded as JSON
• The result is an object
• The classification values are approved
• The summary is not empty
• The recommended reply is not empty
• The action items are an array
• No more than five action items are accepted

Structured Output Versus Function Calling

Structured output controls the format of Gemini's final answer.

Function calling is used when Gemini needs your application to perform an action, such as searching a database, creating an appointment, or retrieving an account record.

We use structured output here because the goal is to receive a predictable final result, not trigger an external action.

Where Structured Output Is Useful

• Extracting contact information
• Classifying support requests
• Analyzing customer feedback
• Creating product data
• Generating form-ready content
• Producing database-ready records
• Creating lists of tasks or recommendations
• Preparing information for another application step

Practical Exercise

1. Analyze the default follow-up message.
2. Review each visible field.
3. Compare the visible cards with the raw JSON.
4. Test the billing complaint.
5. Observe whether urgency and sentiment change.
6. Enter one original business message.
7. Copy the JSON response.
8. Identify which values would be useful for routing a support message automatically.

Lesson Summary

Structured output allows Gemini to return predictable JSON rather than loosely formatted prose.

The schema defines the fields, types, allowed classifications, required values, and array limits. PHP then decodes and validates the returned data before sending it to the browser.

We now have the foundation for AI applications that produce reliable data instead of answers that merely look good on screen.