pydantic-model_skill

Overview

This skill provides Pydantic v2 model patterns tuned for request/response validation, MongoDB conversion, and Travel Panel conventions. It codifies create/update/get model separation, field and model validators, enum usage, and MongoDB doc prep helpers. The goal is consistent, production-ready DTOs and type-safe conversions between API and database shapes.

How this skill works

The skill supplies patterns and example code for building Pydantic v2 BaseModel classes: Create, Update, and Get responses. It emphasizes v2 APIs (model_fields, model_validate, model_dump, model_dump_json, model_validators, field_validator) and shows from_mongo/to_mongo helpers to map MongoDB docs to API responses. It also includes model_config examples, validators for fields and cross-field rules, and enum patterns for fixed values.

When to use it

• Define request and response DTOs for HTTP endpoints and internal services.
• Add validation rules that run on input (field_validator) and across fields (model_validator).
• Convert MongoDB documents into API-safe responses with from_mongo helpers.
• Prepare MongoDB documents for insertion with to_mongo methods including timestamps and ownership fields.
• Enforce strict schemas for partial updates and prevent unknown extra fields.

Best practices

• Always target Pydantic v2 API names and helpers; avoid v1 deprecated attributes.
• Keep separate models for Create (required), Update (optional, forbid extra), and Get (response with from_mongo).
• Use Field(...) for constraints, descriptions, examples, and limits (min_length, max_length, ge, le, pattern).
• Implement @field_validator for per-field normalization and @model_validator(mode='after') for cross-field checks.
• Use enums for fixed sets of values and Optional[...] for nullable fields.
• Use datetime.now(timezone.utc) for created_at/updated_at and include company_id/created_by in to_mongo.

Example use cases

• BookingCreate with validate_dates to ensure check_out > check_in and guests within allowed range.
• BookingUpdate model that forbids extra fields and accepts partial updates only.
• BookingGet.from_mongo that maps MongoDB _id and nested fields into API shape with default fallbacks.
• ItemCreate.to_mongo that attaches company_id, created_by, and UTC timestamps before DB insert.
• CustomerCreate with email and phone field validators to normalize and validate input formats.