Schema Components¶

A schema component defines a structured data type that can be reused across agents, workflows, tools, and transforms. Schemas enforce data contracts -- ensuring that components communicate with well-defined, validated data shapes.

Creating a Schema¶

PythonUI

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

schema = client.schemas.create({
    "name": "Customer Profile",
    "slug": "customer-profile",
    "description": "Standard customer profile structure used across support tools",
    "schema_type": "json_schema",
    "fields": [
        {
            "name": "customer_id",
            "type": "string",
            "description": "Unique customer identifier",
            "required": True,
        },
        {
            "name": "email",
            "type": "string",
            "description": "Customer email address",
            "required": True,
            "validators": [{"type": "pattern", "value": "^[\\w.-]+@[\\w.-]+\\.\\w+$"}],
        },
        {
            "name": "name",
            "type": "string",
            "description": "Full name",
            "required": True,
        },
        {
            "name": "account_tier",
            "type": "string",
            "description": "Subscription tier",
            "required": False,
            "enum": ["free", "starter", "professional", "enterprise"],
            "default": "free",
        },
        {
            "name": "metadata",
            "type": "object",
            "description": "Arbitrary metadata",
            "required": False,
        },
    ],
    "strict_validation": True,
    "tags": ["customer", "shared"],
})

Navigate to Components > Schemas > New. Define fields, types, and validation rules. Click Create.

Configuration¶

Field	Type	Required	Description
`name`	string	Yes	Display name
`slug`	string	Yes	URL-safe identifier
`schema_type`	enum	Yes	`json_schema`, `pydantic`, or `typed_dict`
`fields`	list	Yes	At least one field definition
`strict_validation`	bool	No	Reject extra fields not in the schema (default: `true`)
`examples`	list	No	Example data matching this schema

Schema Types¶

Type	Description	Use Case
`json_schema`	Standard JSON Schema definitions	API contracts, agent output, configuration
`pydantic`	Pydantic model definitions	Python-native validation, type-safe APIs
`typed_dict`	Python TypedDict definitions	Lightweight typing without validation

Field Definitions¶

Each field in the schema defines a data property:

Property	Type	Description
`name`	string	Field name
`type`	string	Data type: `string`, `integer`, `number`, `boolean`, `object`, `array`
`description`	string	Human-readable description
`required`	bool	Whether the field is mandatory
`default`	any	Default value when the field is omitted
`enum`	list	Allowed values for the field
`validators`	list	Validation rules applied to the field

Nested Objects¶

Fields of type object can define nested properties:

fields=[
    {
        "name": "address",
        "type": "object",
        "description": "Mailing address",
        "required": False,
        "properties": {
            "street": {"type": "string"},
            "city": {"type": "string"},
            "state": {"type": "string"},
            "zip": {"type": "string"},
        },
    },
]

Arrays¶

Fields of type array can define the item type:

fields=[
    {
        "name": "tags",
        "type": "array",
        "description": "List of tags",
        "required": False,
        "items": {"type": "string"},
    },
]

Schema Reuse¶

Schemas are designed to be shared across multiple components. A single schema can serve as:

Agent output schema -- Constrains an agent's response structure via schema_refs.output
Workflow input/output -- Defines the data contract for a workflow via input_schema_ref / output_schema_ref
Transform contract -- Specifies expected input and output shapes for transforms
Tool return type -- Defines the structure of a tool's return value via return_schema_ref

graph TD
    Schema["Schema<br/><i>customer-profile</i>"]

    Agent["Agent<br/>schema_refs.output"]
    Workflow["Workflow<br/>input_schema_ref"]
    Transform["Transform<br/>output_schema_ref"]
    Tool["Tool<br/>return_schema_ref"]

    Agent --> Schema
    Workflow --> Schema
    Transform --> Schema
    Tool --> Schema

Share, don't duplicate

When multiple components need the same data structure, create one schema and reference it from all of them. This ensures consistency and makes updates propagate everywhere.

Auto-Generated Schemas¶

The platform can automatically generate schemas in two situations:

From Workflow Edge Conditions¶

When an agent node in a workflow has conditional edges, the platform extracts field references from the condition expressions and generates an output schema:

In the Schema editor, click Generate from workflow edges to auto-generate output schemas from condition expressions. The platform extracts field references (such as category and priority) from the conditions and generates a schema with those fields.

From Code Block Analysis¶

The platform can analyze code block source code and generate input/output schemas using AI:

Click Generate from code block and select a code block to extract its return type as a schema. Choose whether to generate an input or output schema from the code analysis.

Examples¶

Attach examples to a schema for documentation and testing:

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

schema = client.schemas.create({
    "name": "Ticket Classification",
    "slug": "ticket-classification",
    "schema_type": "json_schema",
    "fields": [
        {"name": "category", "type": "string", "required": True,
         "enum": ["billing", "technical", "general"]},
        {"name": "priority", "type": "string", "required": True,
         "enum": ["low", "medium", "high", "critical"]},
        {"name": "summary", "type": "string", "required": True},
    ],
    "examples": [
        {
            "category": "billing",
            "priority": "high",
            "summary": "Customer charged twice for subscription renewal",
        },
        {
            "category": "technical",
            "priority": "medium",
            "summary": "Login page returns 500 error on mobile",
        },
    ],
})

Versioning Schemas¶

Create new versions when the schema structure changes:

Coming Soon

The Python SDK for local development is not yet publicly available.

from flow_sdk.cli_client import CLIClient

client = CLIClient(config)

new_version = client.schemas.create_version(schema.id, {
    "version_increment": "minor",
    "updates": {
        "fields": [
            *existing_fields,
            {"name": "confidence_score", "type": "number",
             "required": False, "description": "Model confidence"},
        ],
    },
    "change_summary": "Added optional confidence_score field",
})

Breaking changes

Adding a required field or removing an existing field is a breaking change. Use a major version increment for breaking changes so that downstream components can pin to a compatible version.