Model Skill

Purpose

Design robust Pydantic v2 data models with full validation and type safety.

Instructions

Basic Model Structure

from pydantic import BaseModel, Field, field_validator, model_validator
from datetime import datetime
from typing import Optional, List
from enum import Enum

class Priority(str, Enum):
    """Task priority levels."""
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    URGENT = "urgent"

class TodoStatus(str, Enum):
    """Task status values."""
    PENDING = "pending"
    COMPLETED = "completed"
    OVERDUE = "overdue"

class RecurrenceType(str, Enum):
    """Task recurrence options."""
    NONE = "none"
    DAILY = "daily"
    WEEKLY = "weekly"
    MONTHLY = "monthly"

Full Model Example

class TodoTask(BaseModel):
    """A todo task with full validation."""
    
    id: int = Field(default=0, description="Unique task identifier")
    title: str = Field(..., min_length=1, max_length=200, description="Task title")
    description: Optional[str] = Field(None, max_length=1000)
    priority: Priority = Field(default=Priority.MEDIUM)
    tags: List[str] = Field(default_factory=list)
    status: TodoStatus = Field(default=TodoStatus.PENDING)
    due_date: Optional[datetime] = None
    created_at: datetime = Field(default_factory=datetime.now)
    updated_at: datetime = Field(default_factory=datetime.now)
    completed_at: Optional[datetime] = None
    recurrence: RecurrenceType = Field(default=RecurrenceType.NONE)
    
    @field_validator('title')
    @classmethod
    def strip_title(cls, v: str) -> str:
        """Strip whitespace from title."""
        return v.strip()
    
    @field_validator('tags')
    @classmethod
    def normalize_tags(cls, v: List[str]) -> List[str]:
        """Normalize tags to lowercase."""
        return [tag.lower().strip() for tag in v if tag.strip()]
    
    @model_validator(mode='after')
    def check_overdue(self) -> 'TodoTask':
        """Auto-set overdue status if past due date."""
        if (self.due_date and 
            self.due_date < datetime.now() and 
            self.status == TodoStatus.PENDING):
            self.status = TodoStatus.OVERDUE
        return self
    
    model_config = {
        "use_enum_values": True,
        "validate_assignment": True,
        "json_encoders": {datetime: lambda v: v.isoformat()},
        "json_schema_extra": {
            "example": {
                "title": "Buy groceries",
                "priority": "medium",
                "tags": ["shopping"]
            }
        }
    }
    
    def to_dict(self) -> dict:
        """Convert to dictionary for storage."""
        return self.model_dump(mode='json')
    
    @classmethod
    def from_dict(cls, data: dict) -> 'TodoTask':
        """Create from dictionary."""
        return cls.model_validate(data)

Validation Patterns

Custom Field Validators

@field_validator('email')
@classmethod
def validate_email(cls, v: str) -> str:
    if '@' not in v:
        raise ValueError('Invalid email format')
    return v.lower()

Cross-field Validation

@model_validator(mode='after')
def validate_dates(self) -> 'Model':
    if self.end_date and self.start_date > self.end_date:
        raise ValueError('end_date must be after start_date')
    return self

Best Practices

• Always use type hints
• Provide descriptions for all fields
• Use Enums for constrained choices
• Add validators for data integrity
• Include examples in schema
• Use model_dump() for serialization
• Use model_validate() for deserialization