Schema Validation

Validate agent outputs against schemas

SchemaValidator ensures agent outputs match expected formats. Catches errors early, before they propagate.

Basic Usage

from splinter.coordination import SchemaValidator

validator = SchemaValidator()

schema = {
    "type": "object",
    "properties": {
        "findings": {"type": "array"},
        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
    },
    "required": ["findings"],
}

# Validate output
output = {"findings": ["a", "b"], "confidence": 0.9}
validator.validate(output, schema)  # ✓ OK

# Invalid output
bad_output = {"confidence": 1.5}  # Missing findings, confidence > 1
validator.validate(bad_output, schema)  # ✗ Raises SchemaValidationError

JSON Schema

We use standard JSON Schema:

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string", "minLength": 1},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "minItems": 1,
        },
        "metadata": {
            "type": "object",
            "properties": {
                "author": {"type": "string"},
                "date": {"type": "string", "format": "date"},
            },
        },
    },
    "required": ["title", "tags"],
}

Registering Agent Schemas

validator = SchemaValidator()

# Register schema for agent output
validator.register_agent_schema("researcher", research_schema)
validator.register_agent_schema("writer", article_schema)

# Validate agent output automatically
validator.validate_agent_output("researcher", output)

Schema from Example

Generate schema from example data:

from splinter.coordination import create_schema_from_example

example = {
    "findings": ["trend1", "trend2"],
    "sources": ["url1", "url2"],
    "confidence": 0.85,
}

schema = create_schema_from_example(example)
# Automatically infers types and structure

Handling Validation Errors

from splinter.exceptions import SchemaValidationError

try:
    validator.validate(output, schema)
except SchemaValidationError as e:
    print(f"Validation failed: {e.message}")
    print(f"Path: {e.path}")
    print(f"Value: {e.value}")
    
    # Get all errors
    for error in e.errors:
        print(f"  - {error.path}: {error.message}")

Partial Validation

Sometimes you want to validate incrementally:

# Validate specific fields only
validator.validate_fields(output, schema, fields=["title", "tags"])

# Validate structure but not values
validator.validate_structure(output, schema)

Best Practices

Define schemas upfront

Before building agents, define what they should output.

Use required fields

Don’t assume optional fields will be present.

Validate early

Check outputs immediately after agent runs, not later.

Include error context

When validation fails, include what was expected vs received.