Input & Output Schemas

How to define form inputs for workflow triggers and structured output fields for execution results

Overview

Schemas define the data contract between users and workflows:

• Input schemas define what the user fills in before triggering a workflow (forms)
• Output schemas define what the workflow returns after execution (results)

Both are defined in config.ts as part of the workflow configuration.

Input schemas

Input schemas are used by HTTP triggers and sub-workflow triggers to define what data the workflow expects.

Structure

An input schema is an array of sections, each containing an array of fields:

function getInputSchema(): FormInputSchema {
  return [
    {
      type: 'section',
      title: 'Configuration',
      collapsible: false,
      inputSchema: [
        {
          key: 'query',
          type: 'text',
          label: 'Search Query',
          description: 'What to search for',
          placeholder: 'Enter your query...',
          required: true,
          maxLength: 1000,
        },
      ],
    },
    {
      type: 'section',
      title: 'Advanced Options',
      collapsible: true,
      inputSchema: [
        {
          key: 'max_results',
          type: 'number',
          label: 'Maximum Results',
          description: 'How many results to return',
          required: false,
          defaultValue: 10,
          min: 1,
          max: 100,
        },
      ],
    },
  ];
}

Field types

Type	Description	Type-specific properties
string	Single-line text	minLength, maxLength, regex, placeholder
text	Multi-line text	minLength, maxLength, rows, placeholder
number	Numeric input	min, max, numberType (integer or float)
boolean	Toggle/checkbox	defaultValue
date	Date picker	minDate, maxDate
select	Single-choice dropdown	options: [{value, label}]
multiselect	Multi-choice dropdown	options: [{value, label}], minItems, maxItems
radio	Radio button group	options: [{value, label}]
file	File upload	maxSize, allowedMimeTypes, maxFiles
array	Repeatable items	itemField: {type, ...}, minItems, maxItems
object	Nested fields	fields: [{key, type, ...}]
objectArray	Repeatable objects	fields: [{key, type, ...}], minItems, maxItems

Common field properties

Property	Type	Description
key	string	Unique field identifier (snake_case or CONSTANT_CASE)
type	string	One of the field types above
label	string	Display label shown to the user
description	string	Help text below the field
placeholder	string	Placeholder text inside the field
required	boolean	Whether the field must be filled
defaultValue	any	Pre-filled value

File upload field

{
  key: 'document',
  type: 'file',
  label: 'Upload Document',
  description: 'PDF, Word, or text file to analyze',
  required: true,
  maxSize: 50 * 1024 * 1024,  // 50 MB
  allowedMimeTypes: ['application/pdf', '.docx', '.doc', '.txt'],
}

Select field

{
  key: 'language',
  type: 'select',
  label: 'Output Language',
  required: true,
  defaultValue: 'english',
  options: [
    { value: 'english', label: 'English' },
    { value: 'french', label: 'French' },
    { value: 'dutch', label: 'Dutch' },
  ],
}

Array field

{
  key: 'urls',
  type: 'array',
  label: 'URLs to process',
  itemField: { type: 'string', maxLength: 500 },
  minItems: 1,
  maxItems: 10,
}

Output schemas

Output schemas define the structure of execution results. They apply to all trigger types.

Structure

An output schema is a flat array of field definitions:

function getOutputSchema(): FormOutputSchema {
  return [
    {
      key: 'summary',
      type: 'text',
      label: 'Analysis Summary',
      description: 'AI-generated summary of the document',
    },
    {
      key: 'confidence',
      type: 'number',
      label: 'Confidence Score',
      description: 'How confident the AI is in the analysis (0-100)',
      numberType: 'integer',
    },
    {
      key: 'categories',
      type: 'array',
      label: 'Detected Categories',
      description: 'List of categories found in the document',
      itemField: { type: 'string' },
    },
    {
      key: 'generated_report',
      type: 'file',
      label: 'Generated Report',
      description: 'PDF report generated by the workflow',
    },
  ];
}

Output field types

Type	Description	Notes
string	Single-line text	Short text values
text	Multi-line text	Long-form content, markdown
number	Numeric value	Use numberType: 'integer' for whole numbers
boolean	True/false	Binary results
date	Date value	ISO 8601 format
file	Uploaded file	References a documentId from Codika Upload File
array	List of items	Requires itemField with type definition

Sub-workflow output schema

Sub-workflows always have an empty output schema:

outputSchema: []

Data flows back to the parent workflow via the Execute Workflow node’s return value.

Connecting schemas to workflow nodes

Input data in workflows

For HTTP triggers, the user’s form data arrives in the webhook payload. Extract it in a Code node:

// In a Code node after Codika Init
const webhookData = $('Webhook Trigger').first().json;
const query = webhookData.body.payload.query;
const maxResults = webhookData.body.payload.max_results || 10;

Output data in workflows

The Codika Submit Result node sends the resultData back. It must match the output schema:

// In a Code node before Codika Submit Result
return {
  json: {
    results: {
      summary: 'Analysis complete...',
      confidence: 95,
      categories: ['finance', 'legal'],
      generated_report: documentId,  // From Codika Upload File
    }
  }
};

Validation

The CLI validates schemas via the schema-types use-case script:

codika-helper verify use-case ./my-use-case

Checks:

• All field types are valid
• Required properties are present
• itemField is defined for array types
• Keys use valid naming conventions