Skip to main content

Pydantic Core Internal Architecture

The architecture of pydantic-core is centered around a high-performance Rust core that provides validation and serialization logic for Python.

The system is divided into two main layers:

  1. Python Interface: This layer defines the CoreSchema, which is a structured dictionary (TypedDict) that describes how data should be validated and serialized. The core_schema module provides helper functions to build these schemas.
  2. Rust Core: The _pydantic_core Rust extension implements the heavy lifting. It takes a CoreSchema from Python and compiles it into a tree of Rust-based validators or serializers.

Key components include:

  • SchemaValidator: The primary entry point for validation. It takes a schema and provides methods like validate_python and validate_json. Internally, it uses a CombinedValidator to dispatch to specific type validators (e.g., StrValidator, IntValidator).
  • SchemaSerializer: The primary entry point for serialization. It converts Python objects into JSON or other Python-compatible formats based on the schema.
  • Input Trait: A crucial abstraction in the Rust core that allows the same validation logic to be applied to different input formats (Python objects, JSON bytes, etc.) without unnecessary conversion.
  • CoreSchema: The "contract" between Python and Rust, defining the structure and constraints of the data.

Key Architectural Findings:

  • The pydantic_core Python package acts as a thin wrapper around the _pydantic_core Rust extension.
  • core_schema.py defines the CoreSchema type, which is the primary configuration format passed from Python to Rust.
  • SchemaValidator and SchemaSerializer are implemented in Rust and exposed to Python via PyO3.
  • The Rust core uses an Input trait to abstract over different data sources (Python objects, JSON), enabling high-performance validation without intermediate Python object creation for JSON.
  • Validation and serialization logic is modularized into specific Rust modules (e.g., src/validators/string.rs, src/serializers/type_serializers/dict.rs).
Loading diagram...