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

# Input Variables

> Define workflow input schema and validation

Input variables define what data your workflow accepts when executed. They're specified using **JSON Schema**, providing documentation, validation, and type safety for workflow inputs.

***

## Why Define Input Schema?

```
Without Schema:
POST /workflows/{id}/execute
{
  "input": { /* anything goes */ }
}
↓
Unclear what's required
Manual validation
Type mismatches
Poor documentation

With Schema:
Documented inputs
Type validation
Required fields enforced
Clear error messages
Self-documenting API
```

***

## Basic Input Schema

### Simple Input

```json theme={null}
{
  "input_schema": {
    "type": "object",
    "properties": {
      "topic": {"type": "string"}
    },
    "required": ["topic"]
  }
}
```

**Valid execution:**

```bash theme={null}
POST /workflows/{id}/execute
{
  "input": {
    "topic": "Machine Learning"
  }
}
```

**Invalid execution:**

```bash theme={null}
POST /workflows/{id}/execute
{
  "input": {}  // ← Error: missing required field "topic"
}
```

### Multiple Required Fields

```json theme={null}
{
  "input_schema": {
    "type": "object",
    "properties": {
      "company_name": {"type": "string"},
      "market": {"type": "string"},
      "year": {"type": "integer"}
    },
    "required": ["company_name", "market", "year"]
  }
}
```

**Valid execution:**

```bash theme={null}
POST /workflows/{id}/execute
{
  "input": {
    "company_name": "Acme Corp",
    "market": "US",
    "year": 2024
  }
}
```

### Optional Fields

```json theme={null}
{
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "depth": {"type": "integer"},
      "include_images": {"type": "boolean"}
    },
    "required": ["query"]  // Only "query" is required
  }
}
```

**All valid:**

```bash theme={null}
{"input": {"query": "AI"}}
{"input": {"query": "AI", "depth": 2}}
{"input": {"query": "AI", "depth": 2, "include_images": true}}
```

***

## JSON Schema Types

### Primitive Types

**String:**

```json theme={null}
{
  "name": {"type": "string"}
}
```

✅ `"John Doe"`
❌ `123`

**Number:**

```json theme={null}
{
  "price": {"type": "number"}
}
```

✅ `99.99`, `100`
❌ `"99.99"`

**Integer:**

```json theme={null}
{
  "count": {"type": "integer"}
}
```

✅ `5`, `-10`
❌ `5.5`

**Boolean:**

```json theme={null}
{
  "active": {"type": "boolean"}
}
```

✅ `true`, `false`
❌ `"true"`

**Null:**

```json theme={null}
{
  "optional_field": {"type": ["string", "null"]}
}
```

✅ `"value"`, `null`

***

## Complex Types

### Arrays

```json theme={null}
{
  "urls": {
    "type": "array",
    "items": {"type": "string"}
  }
}
```

**Valid:**

```json theme={null}
{"urls": ["https://site1.com", "https://site2.com"]}
```

**With min/max items:**

```json theme={null}
{
  "tags": {
    "type": "array",
    "items": {"type": "string"},
    "minItems": 1,
    "maxItems": 10
  }
}
```

### Nested Objects

```json theme={null}
{
  "company": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "details": {
        "type": "object",
        "properties": {
          "founded": {"type": "integer"},
          "headquarters": {"type": "string"}
        }
      }
    },
    "required": ["name"]
  }
}
```

**Valid execution:**

```bash theme={null}
POST /workflows/{id}/execute
{
  "input": {
    "company": {
      "name": "Acme Corp",
      "details": {
        "founded": 1950,
        "headquarters": "New York"
      }
    }
  }
}
```

**Access in workflow:**

```text theme={null}
{{$input.company.name}}
{{$input.company.details.founded}}
```

### Array of Objects

```json theme={null}
{
  "products": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "price": {"type": "number"},
        "in_stock": {"type": "boolean"}
      }
    }
  }
}
```

**Valid execution:**

```bash theme={null}
POST /workflows/{id}/execute
{
  "input": {
    "products": [
      {"id": "SKU001", "price": 99.99, "in_stock": true},
      {"id": "SKU002", "price": 149.99, "in_stock": false}
    ]
  }
}
```

***

## Validation Options

### String Constraints

```json theme={null}
{
  "email": {
    "type": "string",
    "pattern": "^[^@]+@[^@]+\\.[^@]+$"
  },
  "description": {
    "type": "string",
    "minLength": 10,
    "maxLength": 500
  }
}
```

### Number Constraints

```json theme={null}
{
  "priority": {
    "type": "integer",
    "minimum": 1,
    "maximum": 10
  },
  "discount": {
    "type": "number",
    "minimum": 0,
    "maximum": 1
  }
}
```

### Enums (Restricted Values)

```json theme={null}
{
  "market": {
    "type": "string",
    "enum": ["US", "EU", "ASIA", "LATAM"]
  },
  "status": {
    "type": "string",
    "enum": ["active", "inactive", "pending"]
  }
}
```

**Valid:**

```bash theme={null}
{"input": {"market": "US"}}
{"input": {"market": "EU"}}
```

**Invalid:**

```bash theme={null}
{"input": {"market": "CANADA"}}  // ← Not in enum list
```

***

## Complete Example

### Market Research Workflow

**Workflow definition:**

```json theme={null}
{
  "id": "market-research",
  "name": "Market Research Workflow",
  "input_schema": {
    "type": "object",
    "properties": {
      "company_name": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200,
        "description": "Name of company to research"
      },
      "markets": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["US", "EU", "ASIA", "LATAM", "AUSTRALIA"]
        },
        "minItems": 1,
        "maxItems": 5,
        "description": "Target markets for analysis"
      },
      "analysis_depth": {
        "type": "integer",
        "minimum": 1,
        "maximum": 5,
        "description": "Analysis depth (1-5)"
      },
      "include_financial": {
        "type": "boolean",
        "description": "Include financial analysis"
      },
      "competitors": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Competitor companies to compare"
      }
    },
    "required": ["company_name", "markets"],
    "description": "Input for comprehensive market research workflow"
  },
  "nodes": [
    {
      "id": "research_agent",
      "type": "plai_agent",
      "parameters": {
        "agent_name_slug": "researcher",
        "input": "Research {{$input.company_name}} in markets: {{$input.markets | join(', ')}}\n\nDepth: {{$input.analysis_depth}}\nInclude financial: {{$input.include_financial}}\nCompetitors: {{$input.competitors | join(', ')}}"
      }
    }
  ]
}
```

### Valid Execution 1 (Minimal)

```bash theme={null}
POST /workflows/market-research/execute
{
  "input": {
    "company_name": "Acme Corp",
    "markets": ["US", "EU"]
  }
}
```

### Valid Execution 2 (Full)

```bash theme={null}
POST /workflows/market-research/execute
{
  "input": {
    "company_name": "Acme Corp",
    "markets": ["US", "EU", "ASIA"],
    "analysis_depth": 3,
    "include_financial": true,
    "competitors": ["CompetitorA", "CompetitorB"]
  }
}
```

### Invalid Execution 1 (Missing Required Field)

```bash theme={null}
POST /workflows/market-research/execute
{
  "input": {
    "company_name": "Acme Corp"
    // ← Missing "markets" (required)
  }
}
```

**Error:** `"markets" is required`

### Invalid Execution 2 (Wrong Type)

```bash theme={null}
POST /workflows/market-research/execute
{
  "input": {
    "company_name": "Acme Corp",
    "markets": "US"  // ← Should be array
  }
}
```

**Error:** `"markets" must be array`

### Invalid Execution 3 (Enum Value)

```bash theme={null}
POST /workflows/market-research/execute
{
  "input": {
    "company_name": "Acme Corp",
    "markets": ["US", "CANADA"]  // ← CANADA not in enum
  }
}
```

**Error:** `"CANADA" is not an allowed value`

***

## Default Values

Set default values for optional fields:

```json theme={null}
{
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "depth": {"type": "integer"},
      "language": {"type": "string"}
    },
    "required": ["query"]
  }
}
```

**Note:** PLai Framework currently doesn't support JSON Schema `default` keyword. Use conditional logic in nodes:

```json theme={null}
{
  "id": "process",
  "type": "plai_agent",
  "parameters": {
    "input": "Query: {{$input.query}}\nDepth: {%- if $input.depth %}{{$input.depth}}{% else %}2{% endif %}\nLanguage: {%- if $input.language %}{{$input.language}}{% else %}en{% endif %}"
  }
}
```

***

## Input Schema Best Practices

### ✅ DO:

* **Document your inputs:** Include `description` field
* **Be specific:** Use constraints (min/max length, patterns)
* **Use enums:** For restricted value sets
* **Group related inputs:** Use nested objects
* **Provide examples:** In documentation
* **Version your schema:** Track changes

### ❌ DON'T:

* **Use overly permissive schema:** `{"type": "object"}` accepts anything
* **Skip descriptions:** Make intent clear
* **Forget validation:** Catch errors early
* **Use undefined types:** Stick to JSON Schema standards
* **Create deep nesting:** Keep structure simple

***

## Input Schema Documentation Template

```json theme={null}
{
  "input_schema": {
    "type": "object",
    "title": "Workflow Input",
    "description": "Complete description of what this workflow does and requires",
    "properties": {
      "field_name": {
        "type": "string",
        "description": "What this field represents",
        "examples": ["example_value"]
      }
    },
    "required": ["field_name"],
    "examples": [
      {
        "field_name": "example_value"
      }
    ]
  }
}
```

***

## Runtime Input Access

Once workflow is executed, input is always available:

```
In any node:
{{$input.field_name}}       → Access any input field
{{$input}}                  → Entire input object
{{$input | jsonify}}        → Pretty-printed JSON
```

**Example:**

```json theme={null}
{
  "id": "log_input",
  "type": "plai_agent",
  "parameters": {
    "agent_name_slug": "logger",
    "input": "Received input:\n{{$input | jsonify}}"
  }
}
```

***

## Next Steps

* **[Execution Variables](./execution-variables.mdx)** - Use input in workflow nodes
* **[What is a Workflow](./what-is-a-workflow.mdx)** - See complete workflow examples
* **[Node Types](./node-types.mdx)** - Learn about available nodes