---
title: Structured Output for AI Models
description: Define JSON schemas for AI Model steps so responses are predictable, machine-readable, and easier to validate.
icon: "list-check"
---

# 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.

![Thumbnail](./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
{
  "$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"]
}
