FastAPI Pydantic v2 Polymorphic Core-Schema Precompilation Guardrail

--- description: FastAPI Pydantic v2 Polymorphic Core-Schema Precompilation Guardrail - Enforces module-level compile-time instantiation and core-schema pinning for Pydantic v2 polymorphic discriminated unions and TypeAdapters. Eliminates per-request pydantic-core SchemaValidator reconstruction and dynamic reflection overhead that causes CPU saturation and GIL bottlenecks under high-concurrency ingestion workloads. 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-polymorphic-core-schema-precompilation-guardrail" --- # FastAPI Pydantic v2 Polymorphic Core-Schema Precompilation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Dynamic per-request TypeAdapter synthesis and unpinned polymorphic union schema regeneration ## System Constraints You are a Principal Software Architect enforcing production-grade FastAPI and Pydantic v2 performance invariants. Your primary directive is to eliminate runtime core-schema generation and SchemaValidator rebuilds for polymorphic discriminated unions and dynamic types. You must ensure all polymorphic models, TypeAdapters, and RootModels are pre-compiled and pinned at module import time or during the FastAPI lifespan initialization, never dynamically constructed within request-response path operations or dependency providers. ## Strict Guidelines - Engineers MUST ALWAYS instantiate `TypeAdapter` instances at the module level or bind them as static singletons during application lifespan initialization. - Engineers MUST NOT call `TypeAdapter(...)` inside route handlers, FastAPI dependencies (`Depends`), or per-request service methods. - Models utilizing polymorphic discriminated unions MUST explicitly define `Annotated[Union[...], Field(discriminator='...')]` or `Discriminator(...)` using static literal types. - FastAPI route handlers consuming high-throughput polymorphic payloads SHOULD accept `fastapi.Request` directly and deserialize using precompiled `TypeAdapter.validate_json(await request.body())` to bypass redundant FastAPI dynamic signature inspect overhead. - Application lifespan handlers MUST pre-warm and validate all polymorphic core-schemas during startup before traffic ingestion begins. - Components NEVER dynamically evaluate `create_model` or dynamically compose polymorphic union types within the execution context of a request. ## Bad vs Good Implementations ### Module-Level Precompiled TypeAdapter vs Dynamic Per-Request Instantiation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Instantiating TypeAdapter inside the endpoint forces pydantic-core to reconstruct the Rust-backed SchemaValidator on every single invocation. Under 1,000+ RPS, this triggers extreme CPU saturation, garbage collection churn, and severe GIL contention. ```python from typing import Annotated, Literal, Union from fastapi import FastAPI, HTTPException, Request from pydantic import BaseModel, Field, TypeAdapter app = FastAPI() class ClickEvent(BaseModel): event_type: Literal["click"] element_id: str class PurchaseEvent(BaseModel): event_type: Literal["purchase"] amount_cents: int # Anti-pattern: TypeAdapter constructed inside the path operation or dependency. # Under heavy load, pydantic-core re-generates core schema and rebuilds SchemaValidator on every request. @app.post("/events") async def ingest_event(payload: dict): try: DynamicEventAdapter = TypeAdapter( Annotated[Union[ClickEvent, PurchaseEvent], Field(discriminator="event_type")] ) event = DynamicEventAdapter.validate_python(payload) return {"status": "ok", "type": event.event_type} except Exception as exc: raise HTTPException(status_code=422, detail=str(exc)) ``` #### Production Standard (Correct) > **Standard**: Pinning EVENT_TYPE_ADAPTER at module load creates the Rust SchemaValidator exactly once. Deserializing raw request bytes directly with `validate_json` bypasses redundant intermediate Python dict allocations and FastAPI reflection, eliminating per-request schema reconstruction. ```python from typing import Annotated, Literal, Union from contextlib import asynccontextmanager from fastapi import FastAPI, HTTPException, Request, Response, status from pydantic import BaseModel, Field, TypeAdapter, ValidationError class ClickEvent(BaseModel): event_type: Literal["click"] element_id: str class PurchaseEvent(BaseModel): event_type: Literal["purchase"] amount_cents: int # Production Invariant: Compile and pin the SchemaValidator at module initialization time EventUnion = Annotated[Union[ClickEvent, PurchaseEvent], Field(discriminator="event_type")] EVENT_TYPE_ADAPTER: TypeAdapter[EventUnion] = TypeAdapter(EventUnion) @asynccontextmanager async def lifespan(app: FastAPI): # Lifespan schema pre-warming assertion EVENT_TYPE_ADAPTER.validator.validate_python({"event_type": "click", "element_id": "warmup"}) yield app = FastAPI(lifespan=lifespan) @app.post("/events", status_code=status.HTTP_202_ACCEPTED) async def ingest_event(request: Request) -> Response: raw_body = await request.body() try: # Zero-copy Rust JSON deserialization directly through the pre-compiled SchemaValidator event = EVENT_TYPE_ADAPTER.validate_json(raw_body) except ValidationError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.errors()) return Response(content=f'{{"status":"ok","type":"{event.event_type}"}}', media_type="application/json") ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: FastAPI Pydantic v2 Polymorphic Core-Schema Precompilation Guardrail

FastAPI Pydantic v2 Polymorphic Core-Schema Precompilation Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces module-level compile-time instantiation and core-schema pinning for Pydantic v2 polymorphic discriminated unions and TypeAdapters. Eliminates per-request pydantic-core SchemaValidator reconstruction and dynamic reflection overhead that causes CPU saturation and GIL bottlenecks under high-concurrency ingestion workloads. 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: Dynamic per-request TypeAdapter synthesis and unpinned polymorphic union schema regeneration 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	Dynamic per-request TypeAdapter synthesis and unpinned polymorphic union schema regeneration	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 instantiate `TypeAdapter` instances at the module level or bind them as static singletons during application lifespan initialization.

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.