FastAPI Pydantic V2 Strict Polymorphic Deserialization Guardrail

--- description: FastAPI Pydantic V2 Strict Polymorphic Deserialization Guardrail - Enforces strict validation (`strict=True`, `extra='forbid'`) alongside explicit tagged discriminators on all polymorphic unions in FastAPI Pydantic v2 schemas. This eliminates algorithmic complexity attacks (ReDoS/Backtracking CPU exhaustion) caused by sequential union branch evaluation and blocks silent type coercion exploits in nested payloads. globs: app/**/*.py, src/**/*.py, api/**/*.py alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastapi-pydantic-v2-strict-polymorphic-guardrail" --- # FastAPI Pydantic V2 Strict Polymorphic Deserialization Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Lax Untagged Union Deserialization Inducing Silent Type Coercion and Backtracking CPU Exhaustion ## System Constraints You are a Principal Engineer enforcing strict polymorphic deserialization guardrails for FastAPI and Pydantic V2. Mandate invariants that eliminate branch-backtracking DoS vulnerabilities, implicit casting bypasses, and type confusion exploits across all incoming request schemas. ## Strict Guidelines - Engineers MUST ALWAYS use `Annotated[Union[...], Field(discriminator='...')]` or `Discriminator` for any polymorphic payload variants. - Engineers MUST ALWAYS set `model_config = ConfigDict(strict=True, extra='forbid')` on all Pydantic base classes and union member models. - Engineers MUST NOT declare raw `Union[...]` or `TypeA | TypeB` as request body schemas without an explicit discriminator tag. - Models MUST define discriminator fields as exact literal singletons using `Literal[...]` matching the tag value. - Nested polymorphic structures MUST NOT rely on Pydantic's default lax mode coercion (e.g., parsing string '123' as integer or float, or casting falsy values to False). ## Bad vs Good Implementations ### Polymorphic Event Payload Deserialization in FastAPI #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Untagged `Union` requires linear exploration of all candidates. Without `strict=True`, Pydantic attempts data coercion across branches, enabling type-confusion vulnerabilities. Without a discriminator, combinatorial explosion occurs on nested unions, leaving endpoints vulnerable to denial-of-service via CPU exhaustion. ```python from typing import Union from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class PaymentEvent(BaseModel): event_id: str amount: int metadata: dict[str, str] = {} class AuditEvent(BaseModel): event_id: str user_id: int action: str # ANTI-PATTERN: Untagged union with default lax validation. # Pydantic attempts linear evaluation: tries PaymentEvent, coercing fields # if possible. Malicious deeply-nested payloads trigger worst-case branch backtracking # (CPU exhaustion) and silent coercion (e.g., user_id='100' coerced into amount=100). @app.post("/events") def handle_event(payload: Union[PaymentEvent, AuditEvent]): return {"status": "ok", "type": type(payload).__name__} ``` #### Production Standard (Correct) > **Standard**: Using an explicit `discriminator` enables O(1) direct branch selection without sequential trial-and-error backtracking. `strict=True` blocks unexpected type coercion, and `extra='forbid'` eliminates payload stuffing attacks. ```python from typing import Annotated, Literal, Union from fastapi import FastAPI from pydantic import BaseModel, ConfigDict, Field app = FastAPI() class BaseStrictModel(BaseModel): model_config = ConfigDict(strict=True, extra="forbid") class PaymentEvent(BaseStrictModel): event_type: Literal["payment"] event_id: str amount: int metadata: dict[str, str] = Field(default_factory=dict) class AuditEvent(BaseStrictModel): event_type: Literal["audit"] event_id: str user_id: int action: str StrictPolymorphicEvent = Annotated[ Union[PaymentEvent, AuditEvent], Field(discriminator="event_type") ] # PRODUCTION FIX: O(1) discriminator lookup, no silent coercion, forbids unexpected fields @app.post("/events") def handle_event(payload: StrictPolymorphicEvent): return {"status": "ok", "type": payload.event_type} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Pydantic V2 Strict Polymorphic Deserialization Guardrail

FastAPI Pydantic V2 Strict Polymorphic Deserialization Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict validation (`strict=True`, `extra='forbid'`) alongside explicit tagged discriminators on all polymorphic unions in FastAPI Pydantic v2 schemas. This eliminates algorithmic complexity attacks (ReDoS/Backtracking CPU exhaustion) caused by sequential union branch evaluation and blocks silent type coercion exploits in nested payloads. 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 Untagged Union Deserialization Inducing Silent Type Coercion and Backtracking CPU Exhaustion 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 Untagged Union Deserialization Inducing Silent Type Coercion and Backtracking CPU Exhaustion	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 use `Annotated[Union[...], Field(discriminator='...')]` or `Discriminator` for any polymorphic payload variants.

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.