Django Pydantic Field

0.5.4 · active · verified Sat Apr 11

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.

Warnings

breaking Support for Python 3.8 and 3.9 was dropped in version 0.4.0. Projects using these Python versions must either upgrade their Python environment or pin `django-pydantic-field` to a version prior to 0.4.0.
Fix: Upgrade Python to 3.10 or newer, or downgrade `django-pydantic-field` to `<0.4.0`.
breaking Pydantic v2 introduces significant breaking changes (e.g., `dict()` to `model_dump()`, `json()` to `model_dump_json()`, `Config` class to `model_config` dict). While `django-pydantic-field` aims for transparent support, direct interaction with Pydantic models in your application code will require migrating to Pydantic v2's API. Pydantic v1 is also incompatible with Python 3.14 and newer, forcing a Pydantic v2 migration if using newer Python versions.
Fix: 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.
gotcha Serializing complex Pydantic types (e.g., union types like `list[Model] | None`, Pydantic v2 constrained types like `conint`, `Annotated` types, or nested dataclasses) within Django migrations can lead to infinite recursion or incorrect serialization. This has been a recurring issue fixed across several minor releases.
Fix: 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.
gotcha In Pydantic v1, `Optional[Type]` implicitly defaulted to `None`. In Pydantic v2, `Optional[Type]` (or `Type | None`) means the field is required but can accept `None` as a valid value, not that it has a default of `None`. This can lead to unexpected validation errors if `null=True` is not explicitly set on `SchemaField` or if `default=None` is not provided in Pydantic.
Fix: 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.
gotcha `django-pydantic-field` performs validation during Django's `manage.py check` command (e.g., `pydantic.E002: Default value serialization errors`). If your Pydantic schemas or their default values are not correctly serializable, Django's system checks will raise errors.
Fix: 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

pip install django-pydantic-field Install stable version

Imports

SchemaField
```
from django_pydantic_field import SchemaField
```
Older versions (pre-0.1.0) might have used `PydanticSchemaField` from a sub-module, but `SchemaField` directly from the top-level package is the current and recommended import.

Quickstart

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.

import pydantic
import typing
from django.db import models
from django_pydantic_field import SchemaField

# Define a Pydantic model
class Foo(pydantic.BaseModel):
    count: int
    slug: str = "default"

# Define a Django model using SchemaField
class MyModel(models.Model):
    # Django-like style (explicit schema)
    bar = SchemaField(Foo, default={"count": 5})

    # Annotation-based style (Pydantic-like)
    foo: Foo = SchemaField()

    # Supports standard Python types and annotations
    items: list[Foo] = SchemaField(default=list)

    # null=True correctly infers typing.Optional[Foo] for type checkers
    optional_foo = SchemaField(Foo, null=True)

# Example usage (Django shell context assumed):
# obj = MyModel.objects.create(bar={'count': 10, 'slug': 'test-slug'}, foo={'count': 20}, items=[{'count': 1}, {'count': 2}])
# print(obj.bar.count) # Access Pydantic model attributes
# print(obj.foo.slug) # 'default'
# obj.bar = Foo(count=15, slug='new-slug') # Assign Pydantic model directly
# obj.save()

view raw JSON →