home / skills / sickn33 / antigravity-awesome-skills / pydantic-models-py

pydantic-models-py skill

safe

This skill helps you design robust pydantic models using multi-model patterns with Base, Create, Update, Response, and InDB variants.

npx playbooks add skill sickn33/antigravity-awesome-skills --skill pydantic-models-py

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.7 KB

---
name: pydantic-models-py
description: Create Pydantic models following the multi-model pattern with Base, Create, Update, Response, and InDB variants. Use when defining API request/response schemas, database models, or data validation in Python applications using Pydantic v2.
---

# Pydantic Models

Create Pydantic models following the multi-model pattern for clean API contracts.

## Quick Start

Copy the template from [assets/template.py](assets/template.py) and replace placeholders:
- `{{ResourceName}}` → PascalCase name (e.g., `Project`)
- `{{resource_name}}` → snake_case name (e.g., `project`)

## Multi-Model Pattern

| Model | Purpose |
|-------|---------|
| `Base` | Common fields shared across models |
| `Create` | Request body for creation (required fields) |
| `Update` | Request body for updates (all optional) |
| `Response` | API response with all fields |
| `InDB` | Database document with `doc_type` |

## camelCase Aliases

```python
class MyModel(BaseModel):
    workspace_id: str = Field(..., alias="workspaceId")
    created_at: datetime = Field(..., alias="createdAt")
    
    class Config:
        populate_by_name = True  # Accept both snake_case and camelCase
```

## Optional Update Fields

```python
class MyUpdate(BaseModel):
    """All fields optional for PATCH requests."""
    name: Optional[str] = Field(None, min_length=1)
    description: Optional[str] = None
```

## Database Document

```python
class MyInDB(MyResponse):
    """Adds doc_type for Cosmos DB queries."""
    doc_type: str = "my_resource"
```

## Integration Steps

1. Create models in `src/backend/app/models/`
2. Export from `src/backend/app/models/__init__.py`
3. Add corresponding TypeScript types

Overview

This skill generates Pydantic v2 model files using a multi-model pattern: Base, Create, Update, Response, and InDB variants. It provides a reusable template with snake_case and optional camelCase alias support to keep API contracts and database documents consistent. Use it to scaffold models quickly and enforce validation conventions across a Python codebase.

How this skill works

The skill copies a template and replaces resource placeholders with a PascalCase resource name and its snake_case equivalent. It produces model classes with clear responsibilities: a shared Base, a Create model for required fields, an Update model with optional fields, a Response model for API outputs, and an InDB model containing a doc_type for database queries. It also includes Field aliasing and config to accept both snake_case and camelCase when needed.

When to use it

Defining request/response schemas for REST or FastAPI endpoints
Scaffolding consistent models for new resources in a codebase
Creating database-compatible document models with explicit doc_type
Ensuring validation rules and field constraints are centralized
Generating models to match TypeScript types for front-end integration

Best practices

Keep Base minimal: only fields shared across variants
Use Create for required inputs and Update with all Optional[...] fields for PATCH support
Add Field(..., alias="camelCaseName") and set populate_by_name to accept both naming styles
Define doc_type on InDB subclasses to simplify database queries and filtering
Export models from a single package module so imports stay stable

Example use cases

Scaffold Project models: ProjectBase, ProjectCreate, ProjectUpdate, ProjectResponse, ProjectInDB
Create User models that validate email, password rules in Create but omit sensitive fields in Response
Add an InDB model for Cosmos DB with doc_type to speed indexed queries
Generate models alongside TypeScript types to keep API contracts synchronized

FAQ

Can these models accept both snake_case and camelCase JSON?

Yes. Use Field(..., alias="camelCase") on fields and enable populate_by_name so inputs in either naming style are accepted.

Why have separate Create and Update models?

Create enforces required fields for POST operations; Update makes every field optional for PATCH semantics and partial updates.