> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Outputs

> Ensure responses adhere to a JSON schema.

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](https://json-schema.org/overview/what-is-jsonschema). 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.

```python Python theme={null}
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 }
```

```javascript JavaScript theme={null}
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](https://pypi.org/project/pydantic/) (Python) or [Zod](https://www.npmjs.com/package/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](https://developers.datagrid.com/api-reference/converse/modes.md) 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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.