Implementation:Guardrails ai Guardrails Pydantic Model Validator Schema

Knowledge Sources	Guardrails Pydantic Field Docs
Domains	Schema_Definition, Structured_Output
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete pattern for defining Pydantic models with embedded Guardrails validators provided by the guardrails package.

Description

This is a Pattern Doc describing how users define Pydantic models with embedded validator metadata. The extract_validators function in guardrails/schema/pydantic_schema.py traverses the model's fields, reads json_schema_extra["validators"], and builds a ProcessedSchema containing the JSON schema and a validator map keyed by JSON path.

Usage

Use this pattern when defining output schemas for Guard.for_pydantic(). Embed validators directly in field metadata using Field(json_schema_extra={"validators": [ValidatorInstance(on_fail=...)]})}.

Code Reference

Source Location

• Repository: guardrails
• File: guardrails/schema/pydantic_schema.py
• Lines: L167-269 (extract_validators function)

Interface Specification

from pydantic import BaseModel, Field
from guardrails.hub import ValidLength, ToxicLanguage
from guardrails.types.on_fail import OnFailAction

class MyOutputModel(BaseModel):
    """Define output schema with embedded validators."""

    field_name: str = Field(
        description="Description for LLM prompting",
        json_schema_extra={
            "validators": [
                ValidatorInstance(on_fail=OnFailAction.REASK),
                # Add more validators as needed
            ]
        }
    )

Import

from pydantic import BaseModel, Field
from guardrails.types.on_fail import OnFailAction

I/O Contract

Inputs

Name	Type	Required	Description
BaseModel subclass	Type[BaseModel]	Yes	A Pydantic model class with type annotations
json_schema_extra	dict	No	Field metadata containing "validators" key with list of Validator instances

Outputs

Name	Type	Description
Model class	Type[BaseModel]	The Pydantic model class usable with Guard.for_pydantic()
JSON Schema	dict	Automatically derived from the Pydantic model for LLM prompting
Validator map	dict	Mapping from JSON paths to validator instances (built at Guard creation)

Usage Examples

Complete Schema Definition

from pydantic import BaseModel, Field
from guardrails.hub import ValidLength, RegexMatch
from guardrails.types.on_fail import OnFailAction

class UserProfile(BaseModel):
    name: str = Field(
        description="The user's full name",
        json_schema_extra={
            "validators": [
                ValidLength(min=1, max=100, on_fail=OnFailAction.FIX),
            ]
        }
    )
    email: str = Field(
        description="The user's email address",
        json_schema_extra={
            "validators": [
                RegexMatch(
                    regex=r"^[\w\.-]+@[\w\.-]+\.\w+$",
                    on_fail=OnFailAction.REASK
                ),
            ]
        }
    )
    age: int = Field(description="The user's age")

Nested Model

class Address(BaseModel):
    street: str = Field(description="Street address")
    city: str = Field(
        description="City name",
        json_schema_extra={
            "validators": [ValidLength(min=1, max=50, on_fail=OnFailAction.FIX)]
        }
    )

class Person(BaseModel):
    name: str = Field(description="Full name")
    address: Address = Field(description="Home address")

Related Pages

Implements Principle

• Principle:Guardrails_ai_Guardrails_Pydantic_Schema_Definition