Validation System

Moira performs comprehensive validation at multiple levels to ensure workflow integrity and correct agent responses.

Validation Levels

1. JSON Schema Validation

Workflows are validated against a JSON Schema definition:

Structure validation against workflow schema
Required field checking (id, metadata, nodes)
Type validation for all properties
Enum validation for node types

2. Structural Validation

Graph structure is analyzed for correctness:

Node connectivity - All connections point to valid nodes
Required nodes - Start node must exist
Circular dependencies - Loops are detected and flagged
Unreachable nodes - Nodes not connected from start

3. Input Validation

Agent responses are validated against inputSchema:

AJV-based JSON Schema validation
Type checking for response fields
Required field validation
Pattern and format validation

Validation Results

Validation returns structured results:

{
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
}

Error Types

Type	Description	Example
`schema`	JSON structure invalid	Missing required field
`structure`	Graph structure invalid	Orphan node
`connection`	Connection invalid	Points to non-existent node
`reference`	Reference invalid	Invalid subgraph ID

Warning Types

Type	Description	Threshold
`performance`	Large workflow	>20 agent-directive nodes
`complexity`	Complex conditions	Deeply nested conditions
`context`	Large context	>100KB context size

Validation Examples

Valid Workflow

{
  "id": "valid-workflow",
  "metadata": {
    "name": "Valid Workflow",
    "version": "1.0.0",
    "description": "A valid workflow"
  },
  "nodes": [
    { "id": "start", "type": "start", "connections": { "default": "task" } },
    {
      "id": "task",
      "type": "agent-directive",
      "directive": "...",
      "completionCondition": "...",
      "connections": { "success": "end" }
    },
    { "id": "end", "type": "end" }
  ]
}

Result:

{ "valid": true, "errors": [], "warnings": [] }

Invalid Workflow - Missing Connection

{
  "nodes": [
    { "id": "start", "type": "start", "connections": { "default": "missing" } },
    { "id": "end", "type": "end" }
  ]
}

Result:

{
  "valid": false,
  "errors": [
    {
      "type": "connection",
      "message": "Node 'start' references non-existent node 'missing'",
      "nodeId": "start"
    }
  ]
}

Workflow with Warning

Large workflow triggers performance warning:

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "type": "performance",
      "message": "Workflow has 25 agent-directive nodes. Consider breaking into subgraphs.",
      "count": 25
    }
  ]
}

Input Schema Validation

Agent responses are validated against inputSchema defined on agent-directive nodes.

Nodes Without inputSchema

Nodes without inputSchema require empty input from agent. Non-empty responses are rejected:

// Node without inputSchema
{ "id": "task", "type": "agent-directive", "directive": "..." }

// Valid: empty response
{}

// Invalid: non-empty response
{ "result": "done" }  // Rejected with validation error

Schema Definition

{
  "type": "agent-directive",
  "inputSchema": {
    "type": "object",
    "properties": {
      "result": { "type": "string" },
      "confidence": { "type": "number", "minimum": 0, "maximum": 10 }
    },
    "required": ["result"]
  }
}

Valid Response

{ "result": "completed", "confidence": 8 }

Invalid Response

{ "confidence": "high" }

Error:

{
  "valid": false,
  "errors": [
    { "field": "result", "message": "Required field missing" },
    { "field": "confidence", "message": "Expected number, got string" }
  ]
}

Best Practices

Always include inputSchema - Validate agent responses for consistent data
Keep workflows focused - Split large workflows into subgraphs
Test validation - Use manage_workflow with includeValidation: true
Handle errors gracefully - Define error connections for validation failures