fastapi-conventions/sources/pydantic.md

Pydantic source notes for FastAPI conventions

Repo: pydantic/pydantic Local checkout: /home/ubuntu/repos/rodin-sources/pydantic

Why this repo was chosen

• FastAPI's request/response model layer is built on Pydantic. This repo is the right source for boundary-shaping rules: coercion, validation timing, explicit serialization, and validator failure modes.
• Important here because Pydantic's docs include both recommended patterns and dangerous counterexamples.

Repeated patterns

1) Pydantic models are designed for transport boundaries: parse external input, then serialize explicitly

• docs/index.md:61-89 shows raw external input being coerced into a typed BaseModel, including datetime parsing, bytes-to-string coercion, and string-to-int coercion.
• docs/index.md:82-107 uses model_dump() as the explicit serialization boundary.
• docs/index.md:109-152 shows invalid external data producing a structured ValidationError with per-field errors.

Why chosen:

• This is the front-door example in the docs and directly matches how FastAPI uses models for requests and responses.

Caveat / counterexample:

• docs/index.md:93-104 makes clear that default validation is not strict-only; coercion is normal behavior. Any synthesized guidance that assumes "Pydantic means no coercion" would be wrong without an explicit strictness choice.

Implication for synthesis:

• Recommend models at the API boundary, but mention that Pydantic may coerce inputs unless strict behavior is configured.
• Prefer explicit model_dump()/response-model boundaries over ad hoc dict shaping deep in business logic.

2) Use field validators to keep domain-specific checks close to fields, and choose validator timing deliberately

• docs/concepts/validators.md:38-45 defines the contract for field validators: they receive a value and must return the validated value.
• docs/concepts/validators.md:46-80 shows after-validators as the type-safer default because they run after Pydantic's internal validation.
• docs/concepts/validators.md:160-209 shows before-validators receiving raw input, making them useful for coercion/preprocessing before core parsing.

Why chosen:

• These are not isolated APIs; the docs frame validator timing as a central design choice.

Caveat / counterexample:

• docs/concepts/validators.md:160-206 warns that before-validators must handle arbitrary raw input and should avoid unsafe mutation when later raising errors, especially with unions.

Implication for synthesis:

• Prefer after-validators for invariant checks on already-parsed values.
• Use before-validators only when the input truly needs normalization before parsing.

3) Not every validator mode is safe for API-boundary schemas

• docs/concepts/validators.md:254-311 shows plain validators short-circuiting internal validation entirely; the example accepts number='invalid' even though the field is annotated as int.
• docs/concepts/validators.md:313-320 explains that wrap validators can also bypass normal validation flow if they return early or skip the handler.

Why chosen:

• These are exactly the kinds of footguns that can quietly weaken FastAPI request validation if used casually.

Implication for synthesis:

• Avoid recommending plain/wrap validators as the default pattern for request models.
• If they appear in synthesized guidance, frame them as advanced escape hatches with validation-bypass risk.

Strong citation candidates

• External data coercion + explicit serialization boundary: docs/index.md:61-107
• Validation errors are structured and field-specific: docs/index.md:109-152
• Validator contract and return-value requirement: docs/concepts/validators.md:38-45
• After-vs-before validator tradeoff: docs/concepts/validators.md:46-80, docs/concepts/validators.md:160-209
• Plain validators can accept invalid typed data: docs/concepts/validators.md:254-311

Pattern candidates supported by this repo

• use Pydantic models at transport boundaries
• keep serialization explicit with model_dump() or response-model shaping
• prefer after-validators for parsed-value invariants
• use before-validators sparingly for raw-input normalization
• treat plain/wrap validators as advanced tools, not defaults for API schemas