pydantic-models-py/SKILL.md

---

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. license: MIT metadata: author: Microsoft version: "1.0.0"

---

BB Skills adaptation and evidence notes (2026-10-07)

Microsoft authored the original multi-model instructions, Python template and capability reference. All original source files are retained unchanged; upstream-original/SKILL.md holds the original instructions. This identified preface, packaging metadata and the independent examples are BB Skills additions, not Microsoft certification.

The Python asset contains documented resource-name placeholders and is not directly runnable until those placeholders are replaced. The independent fixture makes only those two replacements in memory. Nineteen named model-contract observations passed on Python 3.12.4 with Pydantic 2.13.5 in a disposable Windows virtual environment and separately on the existing 2.7.4 comparison environment. It checks aliases, required fields and length bounds, omitted versus explicit-null updates, upstream extra-field behavior, independent restrictive request models, merged-state validation, JSON-safe output, response projection, the storage discriminator and generated schema. Original Microsoft evaluation criteria are included for reference but the hosted harness was not executed.

The original template defaults to ignoring unknown fields. A regular update model dump includes default null values. For a project contract that needs strict rejection and partial updates, inspect examples/api_contract.py: extra="forbid", exclude_unset=True and validation after merging have different responsibilities. Ownership, permitted workspace access, concurrency and database writes remain application responsibilities. Required fields must remain valid after merging. Response projection in this synthetic fixture is not a comprehensive privacy or API security guarantee.

The pinned template uses populate_by_name=True. Pydantic's current documentation recommends validate_by_name=True and validate_by_alias=True for v2.11 and later; adapt a separate project copy and test the dependency version you pin. Source files are preserved rather than silently rewritten. The 2.7.4 run is comparison evidence, not a downgrade recommendation.

Download, source and offline examples are free and MIT-licensed. Reproduction requires Python and a separately installed Pydantic v2; runtime binaries and wheels are not bundled. No Azure account, cloud database, API key, paid model call, network request by the fixture or production data is required. The skill has not been executed by a complete AI client; runtime_tested remains false. No website API, authentication flow or production persistence was tested. See examples/README.md and native-model-evidence.json for exact environment and boundaries.

Pydantic Models

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

Quick Start

Copy the template from 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

from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field

class MyModel(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    workspace_id: str = Field(..., alias="workspaceId")
    created_at: datetime = Field(..., alias="createdAt")

Optional Update Fields

class MyUpdate(BaseModel):
    model_config = ConfigDict(populate_by_name=True)

    name: Optional[str] = Field(None, min_length=1)
    description: Optional[str] = None

Database Document

class MyInDB(MyResponse):
    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

Reference Files

File	Contents
references/capabilities.md	Additional non-hero capabilities, operation-group coverage, and production checklists.