Connic Composer SDK

Output Schema

Force your LLM agents to return structured JSON output using JSON Schema. Enables reliable data extraction and processing.

Output schemas allow you to define the exact structure of JSON that your LLM agent must return. This is useful for data extraction, form processing, and any task where you need predictable, parseable output.

LLM Agents Only

Output schemas are only supported for type: llm agents. Sequential and tool agents do not support this feature.

Quick Start

1. Create a Schema File

Create a schemas/ directory in your project and add a JSON Schema file:

json

{
  "type": "object",
  "description": "Extracted invoice data",
  "properties": {
    "vendor": {
      "type": "string",
      "description": "Vendor/company name"
    },
    "invoice_date": {
      "type": "string",
      "description": "Invoice date in YYYY-MM-DD format"
    },
    "total": {
      "type": "number",
      "description": "Total invoice amount"
    }
  },
  "required": ["vendor", "total"]
}

2. Reference in Agent YAML

Add the output_schema field to your agent configuration:

yaml

version: "1.0"

name: invoice-extractor
type: llm  # output_schema only works with LLM agents
model: gemini/gemini-2.5-pro
description: "Extracts structured data from invoices"
system_prompt: |
  Extract invoice data and return it as JSON matching the schema.
  Be precise with amounts and dates.

output_schema: invoice-data  # References schemas/invoice-data.json

Project Structure

text

my-project/
├── agents/
│   └── invoice-extractor.yaml
├── schemas/
│   ├── invoice-data.json      # Referenced as "invoice-data"
│   └── customer-info.json     # Referenced as "customer-info"
└── tools/
    └── ...

JSON Schema Basics

Schemas use the JSON Schema standard, a widely-adopted format for describing JSON structure. Here are the key concepts:

Data Types

Type	Example Value	Description
string	"hello world"	Text values
number	42.5	Any numeric value (integers and decimals)
integer	42	Whole numbers only
boolean	true / false	True or false values
array	[1, 2, 3]	List of items (define item schema with `items`)
object	{"key": "value"}	Nested structure (define fields with `properties`)
null	null	Explicit null value

Schema Properties

Property	Used With	Description
type	All	The data type (string, number, object, array, etc.)
description	All	Human-readable description (helps the LLM understand the field)
properties	object	Defines the fields of an object and their schemas
required	object	Array of field names that must be present
items	array	Schema for array elements
enum	string	List of allowed values

Full Example

Here's a more complete schema with nested objects, arrays, and enums:

json

{
  "type": "object",
  "description": "Extracted invoice data",
  "properties": {
    "vendor": {
      "type": "string",
      "description": "Vendor/company name"
    },
    "date": {
      "type": "string",
      "description": "Invoice date (YYYY-MM-DD)"
    },
    "total": {
      "type": "number",
      "description": "Total invoice amount"
    },
    "currency": {
      "type": "string",
      "description": "Currency code",
      "enum": ["USD", "EUR", "GBP"]
    },
    "items": {
      "type": "array",
      "description": "Line items",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "quantity": { "type": "integer" },
          "price": { "type": "number" }
        }
      }
    }
  },
  "required": ["vendor", "total"]
}

Key Points

description helps the LLM understand what data to extract
enum restricts values to a specific set
items defines the schema for array elements
required lists fields that must always be present

Best Practices

Add Descriptions

Always add description to fields. This guides the LLM on what data to extract and improves accuracy.

Use Specific Types

Use integer for counts, number for prices. Be specific about expected formats in descriptions.

Mark Required Fields

Use required to ensure critical fields are always present in the output.

Use Enums for Categories

Use enum to restrict values to a known set (e.g., status codes, categories).

Schema Not Working?

Ensure the schema file is valid JSON (no trailing commas)
Check that the file is in the schemas/ directory
Reference the schema name without the .json extension
Verify your agent type is llm

Learn More

Understanding JSON Schema - Comprehensive guide to the JSON Schema standard
JSON Schema Step by Step - Interactive tutorial

Agent Configuration

Configure agents with output schemas

Local Testing

Test schema validation locally