Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.
Use this skill when
Defining a BaseModel for an HTTP request/response body, config, or domain object
Calling .model_validate(), .model_validate_json(), .model_dump(), .model_dump_json() and handling ValidationError
Writing @field_validator or @model_validator with explicit mode='before' | 'after' | 'wrap'
Using Annotated[T, Field(...), AfterValidator(...)] to compose constraints, validators, and serializers
Modeling tagged unions with Field(discriminator='kind') or callable Discriminator + Tag
Validating non-BaseModel types (list[Item], TypedDict, dataclasses) with TypeAdapter
Generating JSON Schema for OpenAPI / Claude tool definitions via model_json_schema() or TypeAdapter.json_schema()
Loading settings/config from env, .env, or secrets via pydantic-settingsBaseSettings
Migrating Pydantic v1 code (.parse_obj, .dict(), class Config, @validator) to v2
Choosing strict vs lax validation (strict=True, Strict[...] annotation, Field(strict=True))
Do not use this skill when
Task is Zod (TypeScript runtime validation) — →zod
Task is pure Python dataclasses with no validation needed — stay in stdlib
Task is Marshmallow, attrs, or other legacy validators — suggest migrating to Pydantic, don't maintain
Task is Pydantic v1 maintenance with no v2 migration in sight — note the EOL stance; v1 references in migration-from-v1.md
Task is FastAPI request routing wiring without schema design — →fastapi
Task is general Python typing (mapped types, Protocols) with no runtime validation — →python
Purpose
Pydantic is the dominant Python runtime validation library — the bridge between Python type hints and untrusted data (HTTP bodies, env vars, LLM responses, JSON files). It powers FastAPI request/response validation, LangChain tool argument parsing, settings management, and structured LLM outputs. The Rust core (pydantic-core) makes v2 5–50× faster than v1.
Pydantic v2 is a fundamental redesign from v1: methods are prefixed model_* (.model_validate() not .parse_obj(), .model_dump() not .dict()); the inner class Config becomes a model_config = ConfigDict(...) mapping; @validator becomes @field_validator with an explicit mode=; constrained types like constr / conint are replaced by Annotated[T, Field(...)]; and BaseSettings moves to the separate pydantic-settings package. This skill owns the validation layer — the framework skill (fastapi) owns request lifecycle wiring around it.
Capabilities
BaseModel core
Subclass BaseModel, annotate fields with type hints, and Pydantic handles validation and serialization. Construct via Model(**data), Model.model_validate(data) (dict / object), or Model.model_validate_json(bytes_or_str). Serialize via .model_dump() (dict), .model_dump_json() (str), or .model_copy(update={...}). Inspect with Model.model_fields, instance.model_fields_set. Use Model.model_construct(...) only for trusted data — it skips validation. RootModel[list[Item]] for non-object root types.
Field-level: @field_validator('name', mode='before' | 'after' | 'wrap' | 'plain') — after is default and runs on coerced values; before runs on raw input; wrap wraps the inner validator with a handler. Model-level: @model_validator(mode='before' | 'after' | 'wrap') — after is an instance method returning self. The Annotated form (AfterValidator(fn), BeforeValidator(fn), WrapValidator(fn)) makes validators reusable across models. @computed_field exposes a @property as a serialized output. Access other validated fields via info.data, runtime context via info.context.
For tagged unions, Field(discriminator='kind') with Literal['kind'] discriminator fields gives O(1) dispatch and clear errors (pet.dog.barks) instead of trying each variant. For variants whose discriminator field has different names, use Discriminator(callable) paired with Annotated[Variant, Tag('name')] on each member.
class Response[T](BaseModel) (PEP 695) or Generic[T] (3.9+). Parametrize at use site: Response[User]. Generic models cache by type-argument tuple. TypeVar defaults and bounds are supported.
Model.model_json_schema() returns a draft 2020-12 schema dict; TypeAdapter(T).json_schema() does the same for non-models. mode='validation' (default) reflects accepted inputs; mode='serialization' reflects output shape. Customize via Field(json_schema_extra=...) per field or by subclassing GenerateJsonSchema. Used to feed OpenAPI specs (FastAPI auto-wires this) and LLM tool-definition payloads.
