schema-generator

name: fastapi-schema-generator
description: Agent for generating Pydantic schemas
applies_to: fastapi
category: agent
inputs:
  - entity_name: Entity name in PascalCase
  - fields: List of field definitions
  - validations: Custom validation rules

FastAPI Schema Generator Agent

Purpose

Generate Pydantic v2 schemas for request/response validation with proper typing, validators, and OpenAPI documentation.

Activation

• User requests: "create schema for [entity]", "generate [entity] validation"
• When defining API data structures
• When adding validation rules

Generation Process

Step 1: Gather Requirements

Ask for or determine: 1. Entity name (PascalCase): e.g., `Product` 2. Fields and their types 3. Required vs optional fields 4. Validation rules 5. Nested schemas needed 6. Computed fields

Step 2: Analyze Field Types

Map business requirements to Pydantic types:

| Business Type | Pydantic Type | Field Options | |--------------|---------------|---------------| | Short text | `str` | `min_length`, `max_length` | | Email | `EmailStr` | Built-in validation | | URL | `HttpUrl` | Built-in validation | | Integer | `int` | `ge`, `le`, `gt`, `lt` | | Decimal | `Decimal` | `decimal_places` | | Boolean | `bool` | - | | Date | `date` | - | | DateTime | `datetime` | - | | UUID | `UUID` | - | | List | `List[T]` | `min_length`, `max_length` | | Enum | `Literal[...]` | Pattern validation |

Step 3: Generate Schemas

# app/schemas/{entity_lower}.py
"""
{entity_name} Pydantic schemas.

REQ-XXX: {entity_name} data validation
"""
from __future__ import annotations

from datetime import datetime
from decimal import Decimal
from typing import Optional, List
from uuid import UUID

from pydantic import (
    BaseModel,
    Field,
    ConfigDict,
    field_validator,
    model_validator,
)


# ============================================================================
# Base Schema
# ============================================================================

class {entity_name}Base(BaseModel):
    """Base schema with shared fields."""

    name: str = Field(
        ...,
        min_length=1,
        max_length=255,
        description="Display name",
        json_schema_extra={{"example": "Premium Widget"}},
    )
    description: Optional[str] = Field(
        None,
        max_length=2000,
        description="Detailed description",
    )
    price: Decimal = Field(
        ...,
        gt=0,
        decimal_places=2,
        description="Price in dollars",
        json_schema_extra={{"example": 29.99}},
    )
    compare_price: Optional[Decimal] = Field(
        None,
        gt=0,
        decimal_places=2,
        description="Original price for sale display",
    )
    sku: str = Field(
        ...,
        min_length=1,
        max_length=100,
        description="Stock keeping unit",
        json_schema_extra={{"example": "PROD-001"}},
    )


# ============================================================================
# Create Schema
# ============================================================================

class {entity_name}Create({entity_name}Base):
    """Schema for creating a {entity_lower}."""

    category_id: Optional[UUID] = Field(
        None,
        description="Category UUID",
    )
    tags: List[str] = Field(
        default_factory=list,
        max_length=10,
        description="Product tags",
    )
    stock: int = Field(
        default=0,
        ge=0,
        description="Initial stock quantity",
    )
    status: str = Field(
        default="draft",
        pattern="^(draft|active|archived)$",
        description="Initial status",
    )

    @field_validator("name")
    @classmethod
    def validate_name(cls, v: str) -> str:
        """Validate and normalize name."""
        return v.strip()

    @field_validator("tags")
    @classmethod
    def validate_tags(cls, v: List[str]) -> List[str]:
        """Remove duplicates and normalize tags."""
        return list(set(tag.strip().lower() for tag in v if tag.strip()))

    @model_validator(mode="after")
    def validate_prices(self) -> "{entity_name}Create":
        """Validate compare_price > price if set."""
        if self.compare_price and self.compare_price <= self.price:
            raise ValueError("compare_price must be greater than price")
        return self

    model_config = ConfigDict(
        json_schema_extra={{
            "examples": [
                {{
                    "name": "Premium Widget",
                    "description": "High-quality widget",
                    "price": 29.99,
                    "sku": "PROD-001",
                    "tags": ["electronics", "gadgets"],
                }}
            ]
        }}
    )


# ============================================================================
# Update Schema
# ============================================================================

class {entity_name}Update(BaseModel):
    """Schema for updating a {entity_lower}. All fields optional."""

    name: Optional[str] = Field(None, min_length=1, max_length=255)
    description: Optional[str] = Field(None, max_length=2000)
    price: Optional[Decimal] = Field(None, gt=0, decimal_places=2)
    compare_price: Optional[Decimal] = Field(None, gt=0, decimal_places=2)
    sku: Optional[str] = Field(None, min_length=1, max_length=100)
    category_id: Optional[UUID] = None
    tags: Optional[List[str]] = None
    stock: Optional[int] = Field(None, ge=0)
    status: Optional[str] = Field(None, pattern="^(draft|active|archived)$")

    model_config = ConfigDict(extra="ignore")


# ============================================================================
# Response Schema
# ============================================================================

class {entity_name}Response({entity_name}Base):
    """Schema for {entity_lower} response."""

    model_config = ConfigDict(from_attributes=True)

    id: UUID
    slug: str
    status: str
    stoc