Type-Safe Pydantic Schemas for Django JSONFields

django-pydantic-field provides a way to use Pydantic models as schemas for Django's JSONField. It offers full support for Pydantic v1 and v2, type safety and integration with Django's ecosystem, including Forms and Django REST Framework.

Highlights

• Unified API: Transparent support for Pydantic v1 and v2 through the SchemaAdapters.
• Type-Safe: Support for static type checking (ty/mypy/pyright) with type inference for models and annotations.
• Forward References: Lazy resolution of forward references, allowing schemas to be defined anywhere.
• Django Integration: Support for Django Forms and the Admin interface.
• DRF Support: Typed Serializers, Parsers, and Renderers with automatic OpenAPI schema generation via DRF's native schema generator.

Installation

pip install django-pydantic-field

Add "django_pydantic_field" to INSTALLED_APPS in your settings.py to enable automatic integrations (such as Django REST Framework ModelSerializer field mapping and drf-spectacular OpenAPI extensions):

INSTALLED_APPS = [
    ...,
    "django_pydantic_field",
]

Basic Usage

The SchemaField can be used by passing the schema as the first argument (Django-like style) or by using type annotations.

import pydantic
import typing

from django.db import models
from django_pydantic_field import SchemaField


class Foo(pydantic.BaseModel):
    count: int
    slug: str = "default"


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 t.Optional[Foo] for type checkers
    optional_foo = SchemaField(Foo, null=True, default=None)

model = MyModel(foo={"count": 42})
model.save()

# Data is automatically parsed into Pydantic models
assert isinstance(model.foo, Foo)
assert model.foo.count == 42

typing.assert_type(model.optional_foo, Foo | None)

Supported Types

Any type supported by Pydantic can be used as a schema:

• pydantic.BaseModel and pydantic.RootModel (v2)
• Standard Python types (list[str], dict[int, float], etc.)
• dataclasses.dataclass and TypedDict protocols
• typing.Annotated with metadata.

from typing import Annotated
from pydantic import Field


class AdvancedModel(models.Model):
    # Annotated with validation rules
    positive_ints: Annotated[list[int], Field(min_length=1)] = SchemaField()

Forward References & Lazy Resolution

SchemaField supports forward references via string literals or typing.ForwardRef. Resolution is deferred until the first time the field is accessed.

import typing


class MyModel(models.Model):
    foo = SchemaField(typing.ForwardRef("DeferredFoo"))
    another_foo: "DeferredFoo" = SchemaField()


class DeferredFoo(pydantic.BaseModel):
    ...

Error Handling & Schema Evolution

By default, SchemaField validates data strictly when reading from the database or assigning attributes (errors="raise"). When schemas evolve or legacy rows contain invalid data, you can configure how validation errors are handled via the errors argument:

• "raise" (default): Raises django.core.exceptions.ValidationError on invalid data.
• "ignore": Returns the raw unvalidated value (e.g., dict or list) when validation fails, allowing models to be queried, updated, or deleted without crashing.
• "coerce": Falls back to the field's default value, or None if null=True (raises ValidationError if neither is configured).

class EvolvingModel(models.Model):
    # Keep raw data in-place if existing database rows do not match Foo
    legacy_foo: Foo = SchemaField(errors="ignore")

    # Fall back to default value or None on validation failure
    fallback_foo: Foo = SchemaField(default=Foo(count=0), errors="coerce")
    nullable_foo: Foo | None = SchemaField(null=True, errors="coerce")

Pydantic Version Support

The package automatically detects the Pydantic version in your environment and adapts accordingly.

For Pydantic v2 environments, you can still explicitly use Pydantic v1 models by importing from the .v1 subpackage:

from pydantic import v1 as pydantic_v1
from django_pydantic_field.v1 import SchemaField as SchemaFieldV1


class LegacySchema(pydantic_v1.BaseModel):
    ...


class LegacyModel(models.Model):
    legacy_field = SchemaFieldV1(LegacySchema)

Django Forms & Admin

It is possible to create Django forms, which would validate against the given schema:

from django import forms
from django_pydantic_field.forms import SchemaField


class FooForm(forms.Form):
    field = SchemaField(Foo)


form = FooForm(data={"field": '{"slug": "asdf", "count": 1}'})
assert form.is_valid()

django-jsonform support

For a better user experience in the Admin, you can use django-jsonform, which provides a dynamic editor based on the Pydantic model's JSON schema.

from django.contrib import admin
from django_pydantic_field import fields
from django_jsonform.widgets import JSONFormWidget

class MyModelAdmin(admin.ModelAdmin):
    formfield_overrides = {
        fields.PydanticSchemaField: {"widget": JSONFormWidget},
    }

Django REST Framework

Serializers

SchemaField supports explicit schemas, serializer-level type annotations, and automatic resolution inside ModelSerializer (when "django_pydantic_field" is in INSTALLED_APPS or django_pydantic_field.rest_framework is imported):

from rest_framework import serializers
from django_pydantic_field.rest_framework import SchemaField


class MySerializer(serializers.Serializer):
    pydantic_field = SchemaField(Foo)
    annotated_field: list[Foo] = SchemaField()


class MyModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = ("bar", "foo", "items", "optional_foo")

Typed Views (Parsers & Renderers)

You can use SchemaParser and SchemaRenderer to handle Pydantic models directly in your views.

from rest_framework.decorators import api_view, parser_classes, renderer_classes
from rest_framework.response import Response
from django_pydantic_field.rest_framework import SchemaParser, SchemaRenderer

@api_view(["POST"])
@parser_classes([SchemaParser[Foo]])
@renderer_classes([SchemaRenderer[list[Foo]]])
def foo_view(request):
    # request.data is a Foo instance
    instance: Foo = request.data
    return Response([instance])

OpenAPI Generation

drf-spectacular

If you use drf-spectacular with Pydantic v2, django-pydantic-field automatically registers an OpenApiSerializerFieldExtension for django_pydantic_field.rest_framework.SchemaField out of the box—no additional configuration is required.

pip install "django-pydantic-field[spectacular]"

DRF Core AutoSchema

django-pydantic-field also provides an AutoSchema for DRF's built-in schema generator that automatically generates OpenAPI definitions for your Pydantic-backed DRF components.

from django_pydantic_field.rest_framework import AutoSchema

class SampleView(generics.RetrieveAPIView):
    serializer_class = MySerializer
    schema = AutoSchema()

System Checks

The field performs validation during Django's manage.py check command:

• pydantic.E001: Schema resolution errors.
• pydantic.E002: Default value serialization errors.
• pydantic.W003: Data integrity warnings for include/exclude configurations.
• pydantic.W004: Warning when errors="coerce" is set on a non-nullable field without a default value.

Contributing

To get django-pydantic-field up and running in development mode:

1. Install uv;
2. Install the project and its dependencies: uv sync;
3. Setup pre-commit: pre-commit install.
4. Run tests: make test.
5. Run linters: make lint.

Acknowledgement

• Churkin Oleg for his Gist as a source of inspiration