Build

Output Schema

Constrain LLM output to structured JSON and validate it against a supported JSON Schema subset.

Last updated August 20, 2026

On this page

An output schema defines the structure and validation rules for an LLM agent's JSON response. Reference a schema file from the agent YAML to apply it to every response.

LLM Agents Only

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

Final response vs. outbound connectors

output_schema constrains the agent's final response. It does not need to combine the formats of several outbound connectors. An agent-tool outbound connector has its own connector-owned payload schema, validated when the tool is called. A middleware outbound connector accepts the same payload through send_connector. Automatic outbound connectors still interpret the final response as connector content.

Quick Start

Create a Schema File

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

schemas/invoice-data.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"]
}

Reference in Agent YAML

Add the output_schema field to your agent configuration:

agents/invoice-extractor.yaml

version: "1.0"

name: invoice-extractor
type: llm  # output_schema only works with LLM agents
model: connic/gemini-3.7-flash
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

Project structure

my-project/

agents/

invoice-extractor.yaml

schemas/

invoice-data.jsonReferenced as "invoice-data"

customer-info.jsonReferenced as "customer-info"

tools/

...

JSON Schema Basics

Connic accepts the JSON Schema types and keywords listed below. The top-level schema must use type: object; the other types apply to nested properties.

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	primitive	List of allowed values
const	primitive	A single required value
minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf	number	Numeric bounds and increments
minLength, maxLength, pattern	string	String length and regular-expression constraints
minItems, maxItems	array	Array length constraints
default	All	Default-value annotation; it does not make the property required or insert a value when omitted
additionalProperties	object	`false` rejects undeclared fields
nullable / type arrays	All	Use `nullable: true` or `type: ["<type>", "null"]` to allow null

Full Example

A more complete schema with nested objects, arrays, and enums:

schemas/invoice-data.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

Troubleshoot your schema

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

Continue building

Agent Configuration

Configure agents with output schemas

Testing

Lock in schema-validated outputs with declarative tests

Agent YAML

Configure structured output in your agent definition

Assertions

Validate structured output in your test suite