django-pydantic-field integrates Pydantic models with Django's JSONField, offering a type-safe and validated way to store complex data. It provides transparent support for both Pydantic v1 and v2, integrates with Django Forms and Django REST Framework, and enhances static type checking within Django projects. Currently at version 0.5.4, the library is actively maintained with a regular release cadence, addressing compatibility and bug fixes across Django and Pydantic versions.
pip install django-pydantic-fieldVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to define a Pydantic model (`Foo`) and use it within a Django model's `SchemaField`. It shows both explicit schema declaration and annotation-based usage, including support for basic Python types and nullable fields.
Upgrade Python to 3.10 or newer, or downgrade `django-pydantic-field` to `<0.4.0`.
Consult Pydantic's official migration guide for V1 to V2. Use `bump-pydantic` tool for automated code transformation. Leverage `pydantic.v1` namespace if a gradual migration is needed.
Ensure you are on the latest `django-pydantic-field` version. For highly complex schemas, review migration files carefully after generation. Test migrations thoroughly in development environments. Consider simplifying schemas or providing custom migration serialization if issues persist.
For nullable fields, explicitly set `default=None` in your Pydantic model if it should be optional with a `None` default, and set `null=True` on `SchemaField` in your Django model. For mutable defaults (lists, dicts), always use `default_factory=list` or `default_factory=dict` in Pydantic models to prevent shared mutable state across instances.
Ensure all default values for `SchemaField` are JSON serializable. For complex or mutable defaults, use Pydantic's `default_factory` to provide a callable that returns the default value upon instantiation. Run `python manage.py check` regularly to catch these issues early.
Install Pydantic using `pip install pydantic` or ensure it's installed in the active virtual environment. For Pydantic v2, ensure `pydantic-core` is also correctly installed, as it's a critical dependency.
Provide a value for the missing field in the input data, or if the field should be truly optional, define it with a default value, e.g., `field_name: Optional[str] = None`.
Update your code to use `my_model_instance.model_dump()` instead of `my_model_instance.dict()` and `my_model_instance.model_dump_json()` instead of `my_model_instance.json()` when working with Pydantic v2 models.
Inspect the Pydantic model definition used by your `SchemaField` for any syntax errors, unresolved forward references (e.g., string-based type hints for models not yet defined), or invalid default values that cannot be serialized or validated against the schema. Ensure all referenced models are accessible when the Django app loads.
Use the correct import path for `PydanticField` based on your Pydantic version or for auto-detection: `from pydantic_field import PydanticField` (recommended for versions >= 0.5.0) Alternatively, for specific Pydantic versions: `from pydantic_field.v1 import PydanticField` `from pydantic_field.v2 import PydanticField`