Structured Outputs

JSON is one of the most common formats used for data exchange between applications. Structured Outputs is a feature that guarantees the model’s responses will always match your provided JSON Schema. This means you can rely on it to include all required fields and avoid generating invalid enum values or incorrect formats. You can request Datagrid to output a structured response by passing in a JSON Schema into the text.format field. Structured outputs work for every Converse agent_model and chat_mode when you supply text.format; differences between modes are about tools and routing, not about whether schema-constrained JSON is available.

from datagrid_ai import Datagrid
import json

datagrid = Datagrid()

example_json_schema = {
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "The name of the movie"
        },
        "director": {
            "type": "string",
            "description": "The director of the movie"
        },
        "release_year": {
            "type": "number",
            "description": "The year the movie was released"
        }
    },
    "required": ["name", "director", "release_year"],
    "additionalProperties": False
}

response = datagrid.converse(
    prompt="What movie won best picture at the 2001 Oscars?",
    text={"format": example_json_schema}
)

# Structured output is returned as a `json` content item (already parsed).
json_part = next((part for part in response["content"] if part["type"] == "json"), None)
structured_response = json_part["json"] if json_part else None
# => { "name": "Gladiator", "director": "Ridley Scott", "release_year": 2000 }

import Datagrid from "datagrid-ai";

const datagrid = new Datagrid();

const movieJsonSchema = {
    type: "object",
    properties: {
        name: {
            type: "string",
            description: "The name of the movie",
        },
        director: {
            type: "string",
            description: "The director of the movie",
        },
        release_year: {
            type: "number",
            description: "The year the movie was released",
        },
    },
    required: ["name", "director", "release_year"],
    additionalProperties: false,
};

const response = await datagrid.converse({
    prompt: "What movie won best picture at the 2001 Oscars?",
    text: { format: movieJsonSchema },
});

// Structured output is returned as a `json` content item (already parsed).
const jsonPart = response.content.find((part) => part.type === "json");
const structuredResponse = jsonPart?.json;
// => { name: "Gladiator", director: "Ridley Scott", release_year: 2000 }

Libraries such as Pydantic (Python) or Zod (JavaScript) are recommended when manipulating JSON Schemas. Structured output uses the text.format field on the Converse request: you pass a JSON Schema, and the model returns JSON that follows it. Use Modes for how Ask (llm_router), Extended, Execute, and llm-only differ for tools and latency.

Validation and error handling

Structured outputs are enforced server-side. After the agent generates a response, Datagrid validates it against your text.format schema before returning it:

On success, the validated value is returned as a json content item with the value already parsed — you don’t need JSON.parse / json.loads. A JSON-string text content item is also returned, so existing integrations that read content[0].text keep working.
On failure — when the agent cannot produce schema-valid JSON — Datagrid does not return partial or non-conforming data, and no json content item is included. It returns a deterministic error object in a text content item:

{
  "error": {
    "code": "structured_output_generation_failed",
    "message": "The agent did not produce valid JSON for this structured output request."
  }
}

Read the structured result from the json content item (or parse the JSON-string content[0].text), and treat structured_output_generation_failed as a signal to retry the request or relax your schema.

⌘I

Introduction

Converse

Voice

Identity

Agents

Knowledge

Search

Conversations

Messages

Connections

Connection Providers

Connectors

Files

Tools

Secrets

Webhooks

Memory

Pages

MCP Servers - Beta

Batch Predictions

Organization

Validation and error handling

​Validation and error handling

Validation and error handling