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

# Structured output

Defines a JSON response format that the agent will use to structure its output.

<img src="https://mintcdn.com/writer/KruNpIclsgQbhj82/images/agent-builder/blueprints/structured-output-block.png?fit=max&auto=format&n=KruNpIclsgQbhj82&q=85&s=c076d45dd7890a11f83ccb8080ff8c27" alt="" width="2188" height="1456" data-path="images/agent-builder/blueprints/structured-output-block.png" />

## Overview

The **Structured Output** block allows you to define a JSON response format that the AI model uses to structure its output. This is useful when you need the model to return data in a specific schema, such as for downstream processing, API responses, reliable data extraction, or integrations. The block returns the JSON object that matches the schema.

You can specify a prompt describing the data you want, and provide a [JSON Schema](https://json-schema.org/) to enforce the structure of the output. The model attempts to generate a response that matches the schema.

## Common use cases

* Extracting structured data from unstructured text; for example, extracting entities, tables, or key-value pairs
* Generating API responses in a specific format
* Creating objects for further automation or integration
* Enforcing data validation on AI-generated output

## How it works

1. **Prompt**: Describe the data you want the model to generate.
2. **JSON Schema**: Define the required structure for the output. See [JSON Schema](https://json-schema.org/) for more information about how to write a JSON Schema.
3. **Model**: Select the model to use for generation.
4. **Max output tokens**: Set the maximum length of the output.

The block sends the prompt and schema to the model, which returns a JSON object matching the schema. If the output isn't parsable as JSON or doesn't match the schema, the block raises an error.

## Examples

### Data extraction from documents

This example shows how to extract structured data from unstructured documents using AI.

**Blueprint Flow:**

1. **UI Trigger** → User selects a document from the interface
2. **Parse PDF tool** → Extracts text from document. Note: the document must already be uploaded to the Writer cloud.
3. **Structured output** → Extracts specific data fields
4. **HTTP Request** → Sends structured data to external API

**Block Configuration:**

* **Prompt:** "Extract the following information from the document. Document content: @{result}. Return the data in the following format: company name, contact person, email, phone number, and address."

* **JSON Schema:**

  ```json theme={null}
  {
    "type": "object",
    "properties": {
      "company_name": {"type": "string"},
      "contact_person": {"type": "string"},
      "title": {"type": "string"},
      "email": {"type": "string", "format": "email"},
      "phone": {"type": "string"},
      "address": {"type": "string"}
    },
    "required": ["company_name", "contact_person", "email"],
    "additionalProperties": false
  }
  ```

* **Model:** `palmyra-x5`

This workflow enables automated extraction of structured data from unstructured documents.

<img src="https://mintcdn.com/writer/KruNpIclsgQbhj82/images/agent-builder/blueprints/structured-output-workflow.png?fit=max&auto=format&n=KruNpIclsgQbhj82&q=85&s=28b740cca2a244b2001580a4b1446dc5" alt="" width="2104" height="1446" data-path="images/agent-builder/blueprints/structured-output-workflow.png" />

## Fields

<table className="blueprintFields">
  <thead>
    <th>Name</th>
    <th>Type</th>
    <th>Control</th>
    <th>Default</th>
    <th>Description</th>
    <th>Options</th>
    <th>Validation</th>
  </thead>

  <tbody>
    <tr>
      <td>Prompt</td>
      <td>Text</td>
      <td>Textarea</td>

      <td>
        <span>-</span>
      </td>

      <td>Description of a JSON object to be created.</td>

      <td>
        <span>-</span>
      </td>

      <td>
        <span>-</span>
      </td>
    </tr>

    <tr>
      <td>Model</td>
      <td>Model Id</td>
      <td>-</td>

      <td>
        <code>palmyra-x5</code>
      </td>

      <td>-</td>

      <td>
        <span>-</span>
      </td>

      <td>
        <span>-</span>
      </td>
    </tr>

    <tr>
      <td>JSON Schema</td>
      <td>JSON</td>
      <td>-</td>

      <td>
        <code>
          {"{}"}
        </code>
      </td>

      <td>JSON schema that defines the structure of the response. For example, `{"type": "object", "properties": {...}, "required": [...]}`.</td>

      <td>
        <span>-</span>
      </td>

      <td>
        <span>-</span>
      </td>
    </tr>

    <tr>
      <td>Max output tokens</td>
      <td>Number</td>
      <td>-</td>

      <td>
        <code>1024</code>
      </td>

      <td>-</td>

      <td>
        <span>-</span>
      </td>

      <td>
        Range:
        1    to  16384
      </td>
    </tr>
  </tbody>
</table>

## End states

Below are the possible end states of the block call.

<table className="blueprintFields">
  <thead>
    <th>Name</th>
    <th>Field</th>
    <th>Type</th>
    <th>Description</th>
  </thead>

  <tbody>
    <tr>
      <td>Success</td>
      <td>-</td>
      <td>success</td>
      <td>The structured output was generated.</td>
    </tr>

    <tr>
      <td>Error</td>
      <td>-</td>
      <td>error</td>
      <td>There was an error generating the output.</td>
    </tr>
  </tbody>
</table>

The **Structured Output** block returns the JSON object that matches the schema. You can access this value in the following block as `@{result}`.