> ## Documentation Index
> Fetch the complete documentation index at: https://doc.codika.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

```typescript theme={null}
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

```typescript theme={null}
{
  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

```typescript theme={null}
{
  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

```typescript theme={null}
{
  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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```bash theme={null}
codika 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