Skip to main content

Pydantic Core Internal Architecture

The pydantic-core library is structured as a high-performance Rust core with a thin Python wrapper.

The architecture is centered around two main entry points: SchemaValidator and SchemaSerializer. These are exposed to Python via the _pydantic_core extension module.

Key components include:

  • Python Layer: The pydantic_core package provides the public API and re-exports the Rust-implemented classes. The core_schema module defines the structure of schemas that the core can process, primarily using Python TypedDicts.
  • Validation Engine: Implemented in Rust, it builds a tree of specialized validators from the input schema. It uses an Input Abstraction to uniformly process different data formats like Python objects and JSON (via the jiter crate).
  • Serialization Engine: Also in Rust, it builds a tree of serializers. It handles converting complex Python objects back into JSON or plain Python types.
  • Shared Infrastructure: Both engines rely on a Definitions system to handle recursive models and shared references, and a robust Error Handling system to produce detailed ValidationErrors.

The diagram illustrates how data flows from the Python user through the validator/serializer entry points into the specialized Rust logic, and how the Rust core abstracts away the differences between input formats.

Key Architectural Findings:

  • pydantic-core uses a Rust extension (_pydantic_core) to provide high-performance validation and serialization.
  • The SchemaValidator and SchemaSerializer are the primary interfaces between Python and Rust.
  • An 'Input' trait in Rust abstracts over Python objects and JSON data, allowing validators to be format-agnostic.
  • The 'core_schema' Python module defines the contract for schemas using TypedDicts, which are then parsed by Rust to build validator/serializer trees.
  • A shared 'Definitions' system manages recursion and cross-references within schemas.
Loading diagram...