schemas/
├── tools/              # MCP tool parameter validation
│   ├── kanban_create_task.ncl
│   ├── kanban_update_task.ncl
│   ├── assign_task_to_agent.ncl
│   ├── get_project_summary.ncl
│   └── get_agent_capabilities.ncl
│
└── agents/             # Agent task assignment validation
    └── task_assignment.ncl

Schema Format

Nickel schemas define:

Field types (String, Number, Bool, Array, Object)
Required/optional fields (via default values)
Validation contracts (NonEmpty, Email, UUID, Range, Pattern, etc.)
Documentation (via doc annotations)

Example

{
  tool_name = "example_tool",

  parameters = {
    # Required field with contracts
    user_id
      | String
      | doc "User UUID"
      | std.string.NonEmpty
      | std.string.match "^[0-9a-f]{8}-[0-9a-f]{4}-...$",

    # Optional field with default
    priority
      | Number
      | doc "Priority score (0-100)"
      | std.number.between 0 100
      | default = 50,
  },
}

Supported Contracts

Contract	Description	Example
`std.string.NonEmpty`	String cannot be empty	Required text fields
`std.string.length.min N`	Minimum length	`min 3` for titles
`std.string.length.max N`	Maximum length	`max 200` for titles
`std.string.match PATTERN`	Regex validation	UUID format
`std.number.between A B`	Numeric range	`between 0 100`
`std.number.greater_than N`	Minimum value (exclusive)	`> -1`
`std.number.less_than N`	Maximum value (exclusive)	`< 1000`
`std.string.Email`	Email format	user@example.com
`std.string.Url`	URL format	https://...
`std.string.Uuid`	UUID format	xxxxxxxx-xxxx-...
`std.enum.TaggedUnion`	Enum validation	`[

Usage

Schemas are loaded by ValidationPipeline at runtime:

use vapora_shared::validation::{SchemaRegistry, ValidationPipeline};

let registry = Arc::new(SchemaRegistry::new(PathBuf::from("schemas")));
let pipeline = ValidationPipeline::new(registry);

// Validate MCP tool input
let result = pipeline.validate("tools/kanban_create_task", &input).await?;

if !result.valid {
    return (StatusCode::BAD_REQUEST, Json(result.errors));
}

Testing Schemas

Validate schema syntax:

nickel typecheck schemas/tools/kanban_create_task.ncl

Export schema as JSON:

nickel export schemas/tools/kanban_create_task.ncl

Query specific field:

nickel query --field parameters.title schemas/tools/kanban_create_task.ncl

Adding New Schemas

Create .ncl file in appropriate directory
Define tool_name or schema_name
Define parameters or fields with types and contracts
Add doc annotations for documentation
Test with nickel typecheck
Restart services to reload schemas (or use hot-reload)

Hot Reload

Invalidate cached schema without restart:

registry.invalidate("tools/kanban_create_task").await;

Invalidate all schemas:

registry.invalidate_all().await;