Pydantic Models Py

Pydantic Models

Overview

Use this skill to create or refactor Pydantic models for API integration work where request and response contracts must stay explicit, stable, and safe.

The upstream intent is preserved: use a multi-model pattern instead of one overloaded model for every purpose. The enhanced workflow modernizes that pattern for Pydantic v2 and focuses on operational API contract design:

• separate create, update, public response, and internal shapes when their contracts differ
• use aliases intentionally when wire format differs from Python naming
• treat PATCH semantics as distinct from create semantics
• adapt ORM or document objects with from_attributes=True instead of legacy orm_mode
• prevent accidental field leakage by serializing public models, not internal ones

This skill is framework-agnostic Python guidance. FastAPI-style patterns are referenced because they are common and well documented, but the workflow applies to general API integration work.

Version guard: this workflow assumes Pydantic v2 semantics such as model_validate, model_dump, ConfigDict, field_validator, and from_attributes.

When to Use This Skill

Use this skill when:

• you need Pydantic models for an external or internal API contract
• one model is starting to mix input validation, storage fields, and response serialization concerns
• the task requires separate handling for create vs update vs response payloads
• the API uses a different field naming style on the wire, such as camelCase externally and snake_case in Python
• partial updates must preserve the difference between omitted fields and explicit null
• ORM, document, or service-layer objects must be adapted into response models safely

Do not use this skill as the primary router when:

• the user only needs a single ad hoc data container with no contract boundary concerns
• the task is mainly about database schema design rather than API payload design
• the task depends on framework-specific response plumbing more than on Pydantic model design

Operating Table

For selection guidance and config tradeoffs, see references/integration-patterns.md.

Workflow

1. Identify contract boundaries before writing code. Decide whether the task truly needs separate models for create, update, public response, internal response, or persistence. Do not create extra model families unless the payloads differ in a way that matters.

2. Start from the external contract, not the database shape. For API work, define what clients may send and receive first. Persistence-only fields such as internal IDs, doc_type, audit flags, revision tokens, or secret material should not appear in public response models unless explicitly required.

3. Choose a model taxonomy. A practical default is:

   • ThingBase: shared constraints only when reuse is genuinely helpful
   • ThingCreate: fields accepted on creation
   • ThingUpdate: partial-update transport model
   • ThingPublic: fields returned to API clients
   • ThingInternal or ThingInDB: only when internal or persistence needs differ materially

   If Base inheritance makes public/private boundaries fuzzy, prefer separate models instead of inheritance.

4. Set explicit config for request safety. For externally sourced request models, start conservative:

   from pydantic import BaseModel, ConfigDict
   
   class WidgetCreate(BaseModel):
       model_config = ConfigDict(extra='forbid')

   Consider stricter settings intentionally. Reject undeclared fields unless you have a compatibility reason not to. Use default_factory for dynamic defaults instead of mutable literals.

5. Define field naming policy and aliases deliberately. If Python code uses snake_case but the API contract uses camelCase, encode that policy explicitly. Be consistent about whether validation accepts Python names, wire aliases, or both.

   Preferred rule of thumb:

   • keep Python attributes idiomatic in code
   • expose the wire contract through aliases
   • serialize public payloads with by_alias=True when aliases define the contract
   • avoid mixing ad hoc field-level aliasing and broad alias generators without a reason

6. Separate create and update semantics. Create models usually express required writable fields. Update models usually make all updatable fields optional so the transport layer can represent omission.

   Important distinction:

   • omitted field: leave current stored value unchanged
   • field present with null / None: clear it, if the contract allows
   • field present with value: replace or update

   Use model_dump(exclude_unset=True) when applying PATCH-like updates.

7. Validate and adapt at the correct boundary. Use model_validate(...) when building models from request payloads, trusted dictionaries, or class instances. When validating from ORM or document objects, configure the target model with from_attributes=True.

8. Serialize public responses from public models. Prefer:

   • validate an internal object into ThingPublic
   • serialize ThingPublic with model_dump(by_alias=True) if aliases define the contract

   Avoid dumping a richer internal model and trying to hide fields with ad hoc exclude lists.

9. Place business rules carefully. Use field_validator or model_validator for transport and shape validation that belongs to the data contract. Keep workflow-specific side effects, repository checks, and cross-service orchestration in endpoint or service logic.

10. Check generated payloads explicitly. Before finalizing, verify:

    • required vs optional fields match the real contract
    • public output excludes internal metadata
    • aliases serialize exactly as clients expect
    • PATCH behavior preserves omitted fields