FastAPI Pydantic v2 Rust-Core Strict Type Coercion and Deserialization Guardrail

Mandates strict-mode validation across all Pydantic v2 ingress schemas in FastAPI services to prevent silent type mutation, truncation, and injection vulnerabilities. Enforces the Rust-core validator's strict mode (strict=True) to reject loose type casting such as float-to-int rounding, string-to-boolean truthiness evaluation, and precision-lossy float deserialization for monetary figures. Guarantees deterministic cryptographic and financial data contracts before request payloads touch business logic.

--- description: FastAPI Pydantic v2 Rust-Core Strict Type Coercion and Deserialization Guardrail - Mandates strict-mode validation across all Pydantic v2 ingress schemas in FastAPI services to prevent silent type mutation, truncation, and injection vulnerabilities. Enforces the Rust-core validator's strict mode (strict=True) to reject loose type casting such as float-to-int rounding, string-to-boolean truthiness evaluation, and precision-lossy float deserialization for monetary figures. Guarantees deterministic cryptographic and financial data contracts before request payloads touch business logic. globs: app/**/*.py, src/**/*.py, services/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-pydantic-v2-strict-type-coercion-guardrail" --- # FastAPI Pydantic v2 Rust-Core Strict Type Coercion and Deserialization Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Lax Deserialization Allowing Silent Numeric Truncation, Falsy String Coercion, and IEEE-754 Precision Decay ## System Constraints You are a Principal Software Architect enforcing rigorous API ingress integrity for mission-critical financial microservices utilizing FastAPI and Pydantic v2. Pydantic v2's default mode (lax) silently coerces strings to ints, floats to ints by truncation, and integers to booleans inside pydantic-core. You must mandate strict deserialization (`strict=True` or `Strict*` types) across all ingress boundaries, enforce `Decimal` precision for currencies, and eliminate any silent schema mutation before execution reaches service domains. ## Strict Guidelines - Engineers MUST ALWAYS declare `model_config = ConfigDict(strict=True, extra='forbid')` on all ingress request DTOs. - Engineers MUST NEVER use raw `float` for currency, account balances, or trading unit sizes; use `Decimal` with string-enforced ingress parsing or explicit `StrictStr` conversion wrappers. - Engineers MUST ALWAYS enforce explicit primitive parsing using strict wrapper types (`StrictInt`, `StrictStr`, `StrictBool`) when models cannot inherit global strict configuration. - Services MUST reject unexpected JSON payload attributes by setting `extra='forbid'` to mitigate mass-assignment and prototype-style parameter injection risks. - Components NEVER rely on Pydantic's default lax coercion where values like 'yes', 'true', 1, or 0 are dynamically cast to boolean or integer types without explicit parsing semantics. - Engineers MUST register a custom `RequestValidationError` handler in FastAPI to standardize 422 Unprocessable Entity responses into machine-readable, localized error diagnostics without leaking internal stack traces. ## Bad vs Good Implementations ### Ingress Schema Definition with Strict Invariants and Precision Preservation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Pydantic v2 lax mode, floats provided for integer fields are truncated silently without raising a ValidationError, leading to catastrophic financial balance drift. Furthermore, float fields cause IEEE 754 precision degradation, and strings are automatically coerced to booleans. ```python from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() # ANTI-PATTERN: Default lax mode permits silent truncation and coercive deserialization. # e.g., {"amount": 100.99, "cents": 12.8, "is_settled": "true"} -> cents becomes 12 (lossy truncation), # and amount as float suffers IEEE 754 precision loss. class TransactionCreate(BaseModel): account_id: int amount: float cents: int is_settled: bool @app.post("/transactions") async def create_transaction(payload: TransactionCreate): return {"status": "ok", "stored_cents": payload.cents} ``` #### Production Standard (Correct) > **Standard**: By explicitly configuring ConfigDict(strict=True, extra='forbid'), pydantic-core fails fast on any payload attempting to pass floats into integer fields, non-boolean values into boolean fields, or unmapped payload properties. Amount is modeled as an exact Decimal with defined bounds. ```python from decimal import Decimal from fastapi import FastAPI, status from pydantic import BaseModel, ConfigDict, Field, StrictBool, StrictInt app = FastAPI() # PRODUCTION FIX: Strict mode enforced via ConfigDict with extra='forbid' and exact Decimal parsing. class TransactionCreate(BaseModel): model_config = ConfigDict( strict=True, extra="forbid", str_strip_whitespace=True, ) account_id: StrictInt = Field(..., gt=0, description="Unique immutable account identifier") amount: Decimal = Field(..., max_digits=18, decimal_places=4, description="Exact monetary value") cents: StrictInt = Field(..., ge=0, description="Explicit fractional denomination") is_settled: StrictBool = Field(..., description="Boolean state requiring literal true/false") @app.post("/transactions", status_code=status.HTTP_201_CREATED) async def create_transaction(payload: TransactionCreate): return {"status": "accepted", "account_id": payload.account_id, "amount": str(payload.amount)} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Pydantic v2 Rust-Core Strict Type Coercion and Deserialization Guardrail

FastAPI Pydantic v2 Rust-Core Strict Type Coercion and Deserialization Guardrail defines an industrial-grade behavioral standard for backend engineering. Mandates strict-mode validation across all Pydantic v2 ingress schemas in FastAPI services to prevent silent type mutation, truncation, and injection vulnerabilities. Enforces the Rust-core validator's strict mode (strict=True) to reject loose type casting such as float-to-int rounding, string-to-boolean truthiness evaluation, and precision-lossy float deserialization for monetary figures. Guarantees deterministic cryptographic and financial data contracts before request payloads touch business logic. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Lax Deserialization Allowing Silent Numeric Truncation, Falsy String Coercion, and IEEE-754 Precision Decay Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Lax Deserialization Allowing Silent Numeric Truncation, Falsy String Coercion, and IEEE-754 Precision Decay	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS declare `model_config = ConfigDict(strict=True, extra='forbid')` on all ingress request DTOs.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.