Skip to main content

validator Agent

Validate data against schemas. Fail fast on bad input.

Basic Usage

agents:
  - name: validate
    agent: validator
    inputs:
      data: ${input.user_data}
      schema:
        name: string
        email: string
        age: number
Output (success):
{
  "valid": true,
  "data": {
    "name": "Alice",
    "email": "alice@example.com",
    "age": 30
  }
}
Output (failure):
{
  "valid": false,
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Inputs

inputs:
  data:
    type: any
    required: true
    description: Data to validate

  schema:
    type: object
    required: true
    description: Validation schema

  strict:
    type: boolean
    default: true
    description: Fail on extra fields

  coerce:
    type: boolean
    default: false
    description: Coerce types (e.g., "123" � 123)

Schema Syntax

Basic Types

schema:
  name: string
  age: number
  active: boolean
  tags: array
  metadata: object

Required Fields

schema:
  name:
    type: string
    required: true

  email:
    type: string
    required: false

Type Constraints

schema:
  age:
    type: number
    min: 0
    max: 120

  email:
    type: string
    pattern: ^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$

  status:
    type: string
    enum: [active, inactive, pending]

  tags:
    type: array
    minLength: 1
    maxLength: 10
    items: string

Nested Objects

schema:
  user:
    type: object
    properties:
      name: string
      address:
        type: object
        properties:
          street: string
          city: string
          zip:
            type: string
            pattern: ^\d{5}$

Configuration Examples

Basic Validation

agents:
  - name: validate-input
    agent: validator
    inputs:
      data: ${input}
      schema:
        name: string
        age: number

With Error Handling

agents:
  - name: validate
    agent: validator
    inputs:
      data: ${input}
      schema: ${component.user-schema@v1.0.0}

  - name: handle-invalid
    condition: ${!validate.output.valid}
    operation: code
    config:
      code: |
        return {
          status: 400,
          errors: ${validate.output.errors}
        };

Coercion

agents:
  - name: validate
    agent: validator
    inputs:
      data: ${input}
      coerce: true
      schema:
        age: number  # "25" becomes 25
        active: boolean  # "true" becomes true

Strict Mode

agents:
  - name: validate-strict
    agent: validator
    inputs:
      data: ${input}
      strict: true  # Reject extra fields
      schema:
        name: string
        email: string

Advanced Patterns

Multi-Step Validation

agents:
  - name: validate-structure
    agent: validator
    inputs:
      data: ${input}
      schema:
        type: object
        properties:
          email: string

  - name: validate-business-rules
    operation: code
    config:
      code: |
        const user = ${validate-structure.output.data};
        if (user.age < 18) {
          throw new Error('Must be 18+');
        }
        return { valid: true };

Conditional Validation

agents:
  - name: validate-basic
    agent: validator
    inputs:
      data: ${input}
      schema:
        type: string

  - name: validate-premium
    condition: ${input.tier === 'premium'}
    agent: validator
    inputs:
      data: ${input}
      schema:
        features:
          type: array
          minLength: 5

Validate API Response

agents:
  - name: fetch
    operation: http
    config:
      url: https://api.example.com/user/${input.id}

  - name: validate-response
    agent: validator
    inputs:
      data: ${fetch.output.body}
      schema:
        id: number
        name: string
        email: string
        created_at: string

Batch Validation

agents:
  - name: validate-batch
    operation: code
    config:
      code: |
        const results = await Promise.all(
          ${input.items}.map(item =>
            conductor.executeAgent('validator', {
              data: item,
              schema: ${component.item-schema@v1.0.0}
            })
          )
        );
        return {
          valid: results.every(r => r.valid),
          errors: results.filter(r => !r.valid)
        };

Output Schema

{
  valid: boolean;
  data?: any;          // Validated data (if valid)
  errors?: Array<{     // Validation errors (if invalid)
    field: string;
    message: string;
    value?: any;
  }>;
}

Error Messages

The validator provides clear error messages:
{
  "valid": false,
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format",
      "value": "not-an-email"
    },
    {
      "field": "age",
      "message": "Must be between 0 and 120",
      "value": 150
    },
    {
      "field": "status",
      "message": "Must be one of: active, inactive, pending",
      "value": "unknown"
    }
  ]
}

Best Practices

1. Version Your Schemas
schema: ${component.user-schema@v1.2.0}
2. Fail Fast
agents:
  - name: validate
    agent: validator
  - name: process
    condition: ${validate.output.valid}
3. Use Coercion for Forms
inputs:
  coerce: true  # Handle string inputs from forms
4. Validate Early
ensemble: process-user
agents:
  - name: validate
    agent: validator
  # ... rest of pipeline
5. Provide Context in Errors
agents:
  - name: validate
    agent: validator

  - name: format-errors
    condition: ${!validate.output.valid}
    operation: code
    config:
      code: |
        return {
          message: 'Validation failed',
          errors: ${validate.output.errors},
          input: ${input}
        };

Common Schemas

User Registration

schema:
  email:
    type: string
    pattern: ^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$
    required: true

  password:
    type: string
    minLength: 8
    required: true

  name:
    type: string
    required: true

  age:
    type: number
    min: 18
    max: 120

API Webhook

schema:
  event:
    type: string
    enum: [created, updated, deleted]
    required: true

  resource:
    type: object
    required: true
    properties:
      id: string
      type: string

  timestamp:
    type: string
    pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$

E-commerce Order

schema:
  items:
    type: array
    minLength: 1
    items:
      type: object
      properties:
        product_id: string
        quantity:
          type: number
          min: 1
        price:
          type: number
          min: 0

  total:
    type: number
    min: 0
    required: true

  shipping_address:
    type: object
    required: true
    properties:
      street: string
      city: string
      state: string
      zip: string

Next Steps