Workflow:Guardrails ai Guardrails Custom Validator Development
| Knowledge Sources | |
|---|---|
| Domains | LLMs, Validation, Plugin_Development |
| Last Updated | 2026-02-14 12:00 GMT |
Overview
End-to-end process for creating, testing, and optionally publishing custom validators for the Guardrails framework using the Validator base class and registration system.
Description
This workflow covers how to extend Guardrails with custom validation logic beyond what is available on the Hub. Developers implement validators as Python functions (for simple checks) or as classes inheriting from the Validator base class (for stateful or parameterized checks). Validators are registered with the framework via the @register_validator decorator, specifying a name and supported data type. Custom validators can incorporate programmatic rules, ML model inference (e.g., HuggingFace pipelines), or LLM-based evaluation (e.g., using LiteLLM). They support streaming through an overridable chunking function and can provide programmatic fixes via the fix_value field in FailResult.
Usage
Execute this workflow when the existing validators on Guardrails Hub do not cover your specific validation requirements. Common triggers include: enforcing domain-specific business rules, integrating proprietary ML models for content classification, implementing custom toxicity or quality scoring, or adding organization-specific compliance checks. This workflow also applies when contributing new validators back to the Guardrails Hub community.
Execution Steps
Step 1: Choose Validator Implementation Pattern
Decide between a function-based validator (simple, no constructor arguments) or a class-based validator (supports parameters, state, and complex logic). Function validators are defined with a single decorated function. Class validators inherit from Validator and implement the _validate method, with constructor arguments for configuration.
Key considerations:
- Function validators are simpler but cannot accept custom initialization parameters
- Class validators support constructor arguments (e.g., threshold, model_name, word lists)
- Both patterns use the @register_validator decorator with a unique name and data_type
Step 2: Implement Validation Logic
Write the core validation logic in the validate function or _validate method. The method receives the value to validate and a metadata dictionary. It must return either PassResult() for valid input or FailResult(error_message=...) for invalid input. Optionally include a fix_value in FailResult to provide programmatic correction when on_fail="fix" is used.
Key considerations:
- The value parameter type depends on the data_type registered (string, object, etc.)
- The metadata dict passes runtime context from the Guard call to validators
- FailResult.fix_value enables automatic correction without LLM re-prompting
- For ML-based validators, initialize models in __init__ to avoid repeated loading
Step 3: Add Streaming Support
Optionally customize how the validator handles streaming validation by overriding the _chunking_function method. The default strategy validates at sentence boundaries. Custom chunking allows optimization for specific validation types, such as paragraph-level analysis or token-count-based batching.
Key considerations:
- The _chunking_function receives accumulated text and returns split points
- Return an empty list from _chunking_function to indicate insufficient text for validation
- Streaming validation calls _validate with accumulated chunks, not individual tokens
Step 4: Integrate with Guard
Register the custom validator and use it with a Guard via Guard.use(), Guard.use_many(), or as a Pydantic Field validator. The custom validator participates in the same validation pipeline as Hub validators, including on-fail action handling and reask loops.
Key considerations:
- Custom validators must be defined/imported before creating the Guard
- They can be mixed with Hub validators in the same Guard
- For Pydantic integration, pass validator instances in the Field's validators list
Step 5: Submit to Guardrails Hub
Optionally package and submit the validator to Guardrails Hub for community use. Use the guardrails hub create-validator CLI command to scaffold the package structure, or clone the Validator-Template repository for more complex validators. Submit via the CLI or register via the Guardrails Hub website.
Key considerations:
- Hub validators follow a standardized package structure
- The guardrails hub submit command handles packaging and upload
- Complex validators with ML models may use the Validator-Template repository pattern