Implementation:Guardrails ai Guardrails Guard Use Custom Validator

Knowledge Sources	Guardrails
Domains	Validation, Integration
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete method for attaching custom-built validators to a Guard pipeline provided by the guardrails package.

Description

This is the same Guard.use method used for Hub validators, but documented from the perspective of integrating custom validators. The method accepts an instantiated custom Validator, creates a ValidatorReference, and registers it in the Guard's validator map and validator list. The validator's on_fail action (set during instantiation) determines the Guard's behavior when this validator fails.

Usage

Instantiate your custom validator with parameters and an on_fail action, then pass it to Guard().use(). Specify on= to target specific output fields.

Code Reference

Source Location

• Repository: guardrails
• File: guardrails/guard.py
• Lines: L907-940

Signature

def use(
    self,
    validator: UseValidatorSpec,
    *args,
    on: str = "output",
    **kwargs,
) -> "Guard":

Import

from guardrails import Guard

I/O Contract

Inputs

Name	Type	Required	Description
validator	Validator	Yes	Instantiated custom validator with on_fail configured
on	str	No	"output" (default), "messages", or JSON path "$.field"

Outputs

Name	Type	Description
self	Guard	Returns Guard instance for chaining

Usage Examples

End-to-End Custom Validator Integration

from guardrails import Guard
from guardrails.validator_base import Validator, register_validator
from guardrails.classes.validation.validation_result import PassResult, FailResult
from guardrails.types.on_fail import OnFailAction

# 1. Define and register
@register_validator(name="my_org/word_count", data_type="string")
class WordCount(Validator):
    def __init__(self, min_words: int = 1, max_words: int = 500, **kwargs):
        super().__init__(**kwargs)
        self.min_words = min_words
        self.max_words = max_words

    def _validate(self, value, metadata):
        count = len(value.split())
        if self.min_words <= count <= self.max_words:
            return PassResult()
        return FailResult(
            error_message=f"Word count {count} not in [{self.min_words}, {self.max_words}]"
        )

# 2. Instantiate with parameters and on_fail action
validator = WordCount(min_words=10, max_words=200, on_fail=OnFailAction.REASK)

# 3. Attach to Guard
guard = Guard().use(validator)

# 4. Use the Guard
result = guard(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a short bio."}],
)

Related Pages

Implements Principle

• Principle:Guardrails_ai_Guardrails_Custom_Validator_Integration