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

# Structured Output for AI Models

> Define JSON schemas for AI Model steps so responses are predictable, machine-readable, and easier to validate.

# Structured Output for AI Models

> Turn free-form model responses into predictable, well-structured JSON.

With **Structured output (JSON)**, you can define a JSON schema for an **AI Model** step.\
Airia will instruct the model to return responses that conform to this schema so downstream steps can reliably consume the data.

This is ideal for:

* Lead / ticket / incident qualification
* Data extraction from unstructured text
* Routing decisions, classifications, and scoring
* Any workflow that expects **typed fields** instead of free-form text

***

## Enabling Structured Output

1. Open an **AI Model** step in your workflow.
2. Scroll to the **Output** section.
3. Toggle **Structured output** ON.
4. Click **Edit Schema** to configure the JSON schema.

You can edit the schema in two ways:

* **Simple** – A visual table where you define properties, types, and required flags.
* **Advanced** – A raw JSON Schema editor for full control.

Changes in one view are reflected in the other.

***

## Defining Your JSON Schema

In the **Structured output (JSON)** modal, you configure:

### Name

A human-readable name for the schema, e.g. `CompanyDetails`, `QualificationResult`, `RoutingDecision`.

### Properties

Each property becomes a field in the model’s JSON response:

* **Name** – The JSON key, e.g. `company_name`, `industry`.
* **Type** – The data type:
  * `STR` – string
  * `NUM` – number (int or float)
  * `BOOL` – boolean
  * `ARR` – array
  * `OBJ` – nested object
* **Description** – Short, clear description of what the field represents. This is **prompting signal** for the model.
* **Required** – Whether this field must be present in the output.

You can create nested objects (e.g. `address` with `city`, `country`) and arrays of objects for more complex structures.

<img src="https://mintcdn.com/airia/hCvAFBg3lyOv6vWc/building-and-deploying-agents/agent-basics/Images/Example-structured-output-AIStep.png?fit=max&auto=format&n=hCvAFBg3lyOv6vWc&q=85&s=98006bfd796f2bd25a8a44db5c22d201" alt="Thumbnail" width="1682" height="1458" data-path="building-and-deploying-agents/agent-basics/Images/Example-structured-output-AIStep.png" />

***

## How the Model Uses Your Schema

When structured output is enabled:

* The model is instructed to **return valid JSON** that matches your schema.
* It will **attempt** to respect:
  * Field names
  * Types
  * Required vs optional fields

However, the model still operates probabilistically and may need to **fill in gaps** when information is missing.

### Required vs Optional Fields

How missing information is handled depends on your schema and prompt:

#### Required fields

* The model will try to **infer, extrapolate, or generate plausible values** based on context.
* This is useful when you truly need a value, but it can be problematic if the model’s inference is **incorrect**.
* You should **validate** or **confirm** these values when they come from partial input.

#### Optional fields

* Optional fields can be:
  * Omitted from the output, or
  * Set to `null` (if your schema allows it).
* This is safer for information that may not always be available.

> 💡 **Guiding principle**\
> Use **required fields** only for data that is truly critical and should block the workflow if missing.\
> Use **optional or nullable fields** for everything else.

***

## Handling Missing or Uncertain Information

Structured output does *not* replace good workflow design. You still need a strategy for when the user or upstream steps don’t provide enough data.

### 1. Validation & Prompting Strategy

Design the agent to handle missing information **before** calling the AI Model step:

* Check if **critical information** is present (e.g. company name, email, issue type).
* If something important is missing:
  * Prompt the user to provide it first, or
  * Branch to a different path (e.g. a “clarify” step).
* Use a **two-step process** where needed:
  1. Gather / clarify information.
  2. Call the AI Model step with structured output.

This reduces the chance that the model will “fill in” required fields with incorrect guesses.

***

### 2. Default Values & Nullable Types

For non-critical fields, you can use defaults or nullable patterns:

* Define **sensible defaults** in your schema or downstream logic (e.g. `"priority": "medium"`).
* Use **nullable types** (e.g. `string | null`) for fields that might not be provided.
* For optional fields:
  * Allow them to be omitted entirely if not relevant.

This avoids forcing the model to invent values just to satisfy the schema.

***

### 3. Iterative Refinement with the User

For higher-stakes workflows:

1. Let the model generate a **first pass** of the structured output with:
   * Best guesses where appropriate, and/or
   * `null` or omitted fields where information is missing.
2. Present the result back to the **user or another agent** for review.
3. Allow the user to **confirm, edit, or fill in** missing data.
4. Store or use the **confirmed** version in downstream steps.

This pattern works especially well in lead qualification, data enrichment, or compliance-sensitive flows.

***

## Best Practices for Structured Output Prompts

Your prompt should explicitly tell the model **how to behave with missing or uncertain data**.

### 1. Clear Role and Objective

Example system / instructions:

> You are a data extraction assistant that converts user input into a structured JSON object.\
> Your primary goal is to accurately capture provided information and clearly indicate what is missing or uncertain.

### 2. Explicit Rules for Missing Information

You can add strict rules like:

> **Rules for missing information:**
>
> * NEVER guess, invent, or fabricate information that was not explicitly provided.
> * Set fields to `null` if the information is not provided.
> * Use empty strings `""` only for fields that were mentioned but intentionally left blank.
> * For optional fields, omit them entirely if the information is not provided (when allowed by the schema).
> * Do not make assumptions from partial information unless explicitly instructed.

Align these rules with how you configured **required vs optional** fields in the schema.

***

## Example: Company Details Schema

Below is an example of a JSON schema you might use for company data (Advanced view):

```json theme={null}
{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "title": "CompanyDetails",
  "type": "object",
  "properties": {
    "company_name": {
      "type": "string",
      "description": "Official company name"
    },
    "industry": {
      "type": "string",
      "description": "Industry or sector, e.g. SaaS / AI"
    },
    "website": {
      "type": "string",
      "format": "uri",
      "description": "Public website URL"
    },
    "founded_year": {
      "type": "integer",
      "description": "Year the company was founded"
    },
    "employee_count": {
      "type": "integer",
      "description": "Approximate number of employees"
    },
    "address": {
      "type": "object",
      "description": "Headquarters address",
      "properties": {
        "city": { "type": ["string", "null"] },
        "state": { "type": ["string", "null"] },
        "country": { "type": "string" }
      },
      "required": ["country"]
    }
  },
  "required": ["company_name", "website"]
}
```