Input Schema Reference

Overview

Agent-directive nodes use JSON Schema (Draft 7) to validate agent responses. Invalid responses trigger retry with validation error messages.

Basic Structure

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "field_name": { "type": "string" }
    },
    "required": ["field_name"]
  }
}

Type Definitions

String

{
  "properties": {
    "name": { "type": "string" },
    "description": { "type": "string", "minLength": 10 },
    "code": { "type": "string", "maxLength": 100 }
  }
}

Number

{
  "properties": {
    "score": { "type": "number", "minimum": 0, "maximum": 100 },
    "count": { "type": "integer", "minimum": 1 }
  }
}

Boolean

{
  "properties": {
    "confirmed": { "type": "boolean" }
  }
}

Array

{
  "properties": {
    "items": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 10
    }
  }
}

Object

{
  "properties": {
    "config": {
      "type": "object",
      "properties": {
        "enabled": { "type": "boolean" },
        "value": { "type": "number" }
      },
      "required": ["enabled"]
    }
  }
}

Enum Constraints

String Enum

{
  "properties": {
    "status": { "type": "string", "enum": ["pending", "approved", "rejected"] },
    "decision": { "type": "string", "enum": ["yes", "no"] }
  }
}

Boolean-like Enum

For Russian responses:

{
  "properties": {
    "confirmed": { "type": "string", "enum": ["да", "нет"] }
  }
}

Use string enums for yes/no instead of booleans. This makes agent responses more explicit and consistent.

Optional vs Required

Required Fields

{
  "required": ["result", "confidence"]
}

Optional Fields with Default

{
  "properties": {
    "verbose": { "type": "boolean", "default": false }
  }
}

Optional Skip Pattern

{
  "properties": {
    "result": { "type": "string" },
    "skip": { "type": "string", "enum": ["yes"] }
  }
}

Agent provides either result or skip, not both.

Pattern Validation

File Path Pattern

{
  "properties": {
    "file_path": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9/_.-]+\\.(json|yaml|md)$"
    }
  }
}

Email Pattern

{
  "properties": {
    "email": {
      "type": "string",
      "pattern": "^[^@]+@[^@]+\\.[^@]+$"
    }
  }
}

URL Pattern

{
  "properties": {
    "url": {
      "type": "string",
      "pattern": "^https?://"
    }
  }
}

Array Validation

Typed Array Items

{
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

Object Array Items

{
  "properties": {
    "steps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "status": { "type": "string", "enum": ["done", "pending"] }
        },
        "required": ["name", "status"]
      },
      "minItems": 1
    }
  }
}

Additional Properties

Strict Schema (Default)

{
  "type": "object",
  "properties": {
    "result": { "type": "string" }
  },
  "required": ["result"],
  "additionalProperties": false
}

Rejects any fields not defined in properties. The engine automatically enforces additionalProperties: false on all object schemas with properties, so this is the default behavior even without explicit setting.

Allow Extra Fields

{
  "additionalProperties": true
}

Explicitly set additionalProperties: true to allow undefined fields.

Description for Agents

Add descriptions to help agents understand fields:

{
  "properties": {
    "issues_count": {
      "type": "number",
      "minimum": 0,
      "description": "Number of reproducible blocking findings in the report; zero is valid"
    },
    "evidence": {
      "type": "string",
      "description": "Concrete proof that work is complete (test output, command results)"
    }
  }
}

note: Descriptions are shown to agents in validation errors and help prompts.

Magic Variables

Special variable execution_note updates execution tracking:

{
  "properties": {
    "execution_note": {
      "type": "string",
      "description": "Note to identify this execution"
    }
  }
}

See Magic Variables for details.

Common Patterns

Yes/No Response

{
  "type": "object",
  "properties": {
    "result": { "type": "string", "enum": ["yes", "no"] },
    "reason": { "type": "string" }
  },
  "required": ["result"]
}

Numeric with Evidence

{
  "type": "object",
  "properties": {
    "error_count": { "type": "number", "minimum": 0 },
    "evidence": { "type": "string", "minLength": 10 }
  },
  "required": ["error_count", "evidence"]
}

Multi-Choice

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": ["create", "edit", "delete", "skip"]
    },
    "details": { "type": "string" }
  },
  "required": ["action"]
}