Serializing models and Querysets#

Quote of the day

There are things that are easy.

There are things that seem easy.

Usually they are different things.

—Nikita Sobolev, CPython core developer

Django is built around its QuerySet type. Of course, we make sure that it is supported.

Prepare yourself for a wild ride! This section will not only be about queryset, but also about the architecture of Django applications.

Important

We offer a brand new way of working with QuerySet.

It is the best thing that ever happened to Django’s serialization.

We built our serialization patterns on:

Simplicity
Database table independence from the serialization schema
Customizability: you can change anything at any time
Performance: no extra fields, no extra queries, fast serialization
Everything must be typed at all times

Oversimplied example#

Let’s start with the very simple definition of a regular model with no foreign keys or many-to-many fields.

Our approach is to always move all the business logic away from the view. Even in examples, because they form the habit of developers and LLMs who are reading it.

Model#

Our regular Model definition:

models.py#

[source]

from typing import final

from django.db import models


@final
class User(models.Model):
    # This is sent to us from another service:
    email = models.EmailField(unique=True)
    customer_service_uid = models.UUIDField(unique=True)

    # Our own fields:
    is_active = models.BooleanField(db_index=True, default=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

For this example, the model won’t have any FK or M2M fields. In the next examples we will show how to work with them as well.

Serializer schemas#

Next, let’s define serializer schemas to get the incoming data and return the response.

You can use any schema type, such as msgspec.Struct, pydantic.BaseModel, attrs.define(), typing.TypedDict, etc. We will use pydantic for this example, because it is the most familiar concept among them for most developers:

serializers.py#

[source]

import datetime as dt
import uuid
from typing import Annotated, TypeAlias, final

import pydantic

DatabaseId: TypeAlias = Annotated[int, pydantic.Field(gt=0)]


class SimpleUserCreateSchema(pydantic.BaseModel):
    email: str
    customer_service_uid: uuid.UUID


@final
class SimpleUserSchema(SimpleUserCreateSchema):
    id: DatabaseId
    created_at: dt.datetime

Important

This step is really important! We have to separate database models and serializer schemas from each other. Why?

Because it gives us more control over the serialization process both ways
Because new database fields will not automatically appear in your API spec
Because removing a database field will not break the API contract
Because versioning the API becomes much easier
Because explicit typing will let you catch more errors earlier

Services#

Now, let’s define our business logic.

Note

We don’t give any architectural advice here, you can use any approach that you like for your projects: DDD, Clean or Hexagonal Architecture, Functional Core and Imperative Shell, whatever you like.

However, we strongly recommend that you separate your business logic from views for better testing and better composition.

For this example, we will use the simplest services.py layer for our business logic:

services.py#

[source]

from typing import final

from django.db import IntegrityError
from django.db.models import QuerySet

from server.apps.model_simple.models import User
from server.apps.model_simple.serializers import SimpleUserCreateSchema


@final
class UniqueConstraintError(Exception):
    """Fields ``email`` and ``customer_service_uid`` must be unique."""


def user_create_service(user_schema: SimpleUserCreateSchema) -> User:
    """This is a function just for the demo's purpose, it is usually a class."""
    try:
        return User.objects.create(
            email=user_schema.email,
            customer_service_uid=user_schema.customer_service_uid,
        )
    except IntegrityError:
        # We don't raise `IntegrityError` here, because we prefer domain
        # exceptions over Django ones. It is much easier to manage.
        raise UniqueConstraintError from None


def user_list_service() -> QuerySet[User]:
    """Return all users."""
    # Only can exclude fields that we won't use by passing as a param
    # `UserSchema.__struct_fields__` tuple and calling `.only(*fields)` here:
    return User.objects.all()

There’s nothing fancy about it. Just creating a model from the typed input data.

Views#

Now, we can define views that will use everything defined above.

Just convert models from attributes, using the builtin .model_validate() converter. For msgspec one can use msgspec.convert().

The main reason to use this approach is that it is short and easy
The main reason not to use this approach is that errors will only show up during tests. Not during type-checking. For example, removing customer_service_uid from models.py (for some business reason) will not trigger any type checking errors. If this line is not covered with tests, your API will not work:
```
Traceback (most recent call last):
  File "server/apps/model_simple/views/minimalistic.py", line 42
    return UserSchema.model_validate(
    ~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
pydantic.ValidationError: Object missing required field `customer_service_uid`
```

views.py#

[source]

from http import HTTPStatus
from typing import Final, final

import pydantic
from django.http import HttpResponse
from typing_extensions import override

from dmr import Body, Controller, modify
from dmr.endpoint import Endpoint
from dmr.errors import ErrorType
from dmr.metadata import ResponseSpec
from dmr.plugins.pydantic import PydanticSerializer
from server.apps.model_simple.serializers import (
    SimpleUserCreateSchema,
    SimpleUserSchema,
)
from server.apps.model_simple.services import (
    UniqueConstraintError,
    user_create_service,
    user_list_service,
)

_UserList: Final = pydantic.TypeAdapter(list[SimpleUserSchema])


@final
class UserController(Controller[PydanticSerializer]):
    def get(self) -> list[SimpleUserSchema]:
        """List existing users."""
        return _UserList.validate_python(
            user_list_service(),
            from_attributes=True,
        )

    @modify(
        extra_responses=[
            ResponseSpec(
                Controller.error_model,
                status_code=HTTPStatus.CONFLICT,
            ),
        ],
    )
    def post(
        self,
        parsed_body: Body[SimpleUserCreateSchema],
    ) -> SimpleUserSchema:
        """Create new user."""
        return SimpleUserSchema.model_validate(
            user_create_service(parsed_body),
            from_attributes=True,
        )

    @override
    def handle_error(
        self,
        endpoint: Endpoint,
        controller: Controller[PydanticSerializer],
        exc: Exception,
    ) -> HttpResponse:
        # Handle custom errors that can happen in this controller:
        if isinstance(exc, UniqueConstraintError):
            return self.to_error(
                self.format_error(
                    'User `email` and `customer_service_uid` must be unique',
                    error_type=ErrorType.value_error,
                ),
                status_code=HTTPStatus.CONFLICT,
            )
        # Handle default errors:
        return super().handle_error(endpoint, controller, exc)

Run result

$ curl http://127.0.0.1:8000/api/users/ -X POST -d '{"email": "minimalistic@example.com", "customer_service_uid": "e87035e1-27a6-4e6b-a61a-d395bd4e221a"}' -H 'Content-Type: application/json'
{"email":"minimalistic@example.com","customer_service_uid":"e87035e1-27a6-4e6b-a61a-d395bd4e221a","id":1,"created_at":"2026-10-05T11:18:06.969336Z"}

$ curl http://127.0.0.1:8000/api/users/ -X GET
[{"email":"minimalistic@example.com","customer_service_uid":"e87035e1-27a6-4e6b-a61a-d395bd4e221a","id":1,"created_at":"2026-10-05T11:18:06.969336Z"}]

Convert models to schemas manually. It might seem like a lot of code, but actually, it is pretty simple to do (especially with the help of an LLM).

The main reason to use this approach is correctness. For example, removing the customer_service_uid model field will now trigger an early type-checking error, unlike the “Minimalistic” version, which will only fail at runtime:

server/apps/model_simple/views/detailed.py:28: error: "User" has no attribute "customer_service_uid"  [attr-defined]
server/apps/model_simple/views/detailed.py:48: error: "User" has no attribute "customer_service_uid"  [attr-defined]

The main reason not to use this approach is its verbosity

views.py#

[source]

from http import HTTPStatus
from typing import final

from django.http import HttpResponse
from typing_extensions import override

from dmr import Body, Controller, modify
from dmr.endpoint import Endpoint
from dmr.errors import ErrorType
from dmr.metadata import ResponseSpec
from dmr.plugins.pydantic import PydanticSerializer
from server.apps.model_simple.serializers import (
    SimpleUserCreateSchema,
    SimpleUserSchema,
)
from server.apps.model_simple.services import (
    UniqueConstraintError,
    user_create_service,
    user_list_service,
)


@final
class UserController(Controller[PydanticSerializer]):
    def get(self) -> list[SimpleUserSchema]:
        """List existing users."""
        return [
            SimpleUserSchema(
                id=user.pk,
                email=user.email,
                customer_service_uid=user.customer_service_uid,
                created_at=user.created_at,
            )
            for user in user_list_service()
        ]

    @modify(
        extra_responses=[
            ResponseSpec(
                Controller.error_model,
                status_code=HTTPStatus.CONFLICT,
            ),
        ],
    )
    def post(
        self,
        parsed_body: Body[SimpleUserCreateSchema],
    ) -> SimpleUserSchema:
        """Create new user."""
        user = user_create_service(parsed_body)
        return SimpleUserSchema(
            id=user.pk,
            email=user.email,
            customer_service_uid=user.customer_service_uid,
            created_at=user.created_at,
        )

    @override
    def handle_error(
        self,
        endpoint: Endpoint,
        controller: Controller[PydanticSerializer],
        exc: Exception,
    ) -> HttpResponse:
        # Handle custom errors that can happen in this controller:
        if isinstance(exc, UniqueConstraintError):
            return self.to_error(
                self.format_error(
                    'User `email` and `customer_service_uid` must be unique',
                    error_type=ErrorType.value_error,
                ),
                status_code=HTTPStatus.CONFLICT,
            )
        # Handle default errors:
        return super().handle_error(endpoint, controller, exc)

Run result

$ curl http://127.0.0.1:8000/api/users/ -X POST -d '{"email": "detailed@example.com", "customer_service_uid": "616d51f2-2c31-4b04-8034-2f59eae042db"}' -H 'Content-Type: application/json'
{"email":"detailed@example.com","customer_service_uid":"616d51f2-2c31-4b04-8034-2f59eae042db","id":2,"created_at":"2026-10-05T11:18:08.001687Z"}

$ curl http://127.0.0.1:8000/api/users/ -X GET
[{"email":"minimalistic@example.com","customer_service_uid":"e87035e1-27a6-4e6b-a61a-d395bd4e221a","id":1,"created_at":"2026-10-05T11:18:06.969336Z"},{"email":"detailed@example.com","customer_service_uid":"616d51f2-2c31-4b04-8034-2f59eae042db","id":2,"created_at":"2026-10-05T11:18:08.001687Z"}]

Now you have your REST API that returns fully typed model responses and can work with QuerySet and Model instances.

Realistic example#

Now, let’s see how a more realistic layout may look like. It will include:

ForeignKey relationship
ManyToMany relationship
DI for realistic expectations
Mappers and services separate layers

Models#

We start with model definitions.

models.py#

[source]

from typing import final

from django.db import models


@final
class Tag(models.Model):
    name = models.CharField(max_length=100, unique=True)

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)


@final
class Role(models.Model):
    name = models.CharField(max_length=100, unique=True)

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)


@final
class User(models.Model):
    # This is sent to us from another service:
    email = models.EmailField(unique=True)

    # Linking:
    role = models.ForeignKey(
        Role,
        on_delete=models.CASCADE,
        related_name='users',
    )
    tags = models.ManyToManyField(Tag, related_name='users')

    # Our own fields:
    is_active = models.BooleanField(db_index=True, default=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

We added two models:

Role for a foreign key relation
Tag for a many-to-many relation

Serializer schemas#

Next, let’s see how serializer schemas are defined.

serializers.py#

[source]

import datetime as dt
from typing import Annotated, TypeAlias, final

import pydantic

DatabaseId: TypeAlias = Annotated[int, pydantic.Field(gt=0)]


@final
class PageQuery(pydantic.BaseModel):
    page_size: int = pydantic.Field(default=10, ge=1, le=100)
    page: int = pydantic.Field(default=1, ge=1)

    model_config = pydantic.ConfigDict(extra='forbid')


@final
class TagSchema(pydantic.BaseModel):
    name: str = pydantic.Field(max_length=100)


@final
class RoleSchema(pydantic.BaseModel):
    name: str = pydantic.Field(max_length=100)


class UserCreateSchema(pydantic.BaseModel):
    email: str
    role: RoleSchema
    tags: list[TagSchema]


@final
class UserSchema(UserCreateSchema):
    id: DatabaseId
    created_at: dt.datetime

Note that we model foreign key and many-to-many relations here as nested schemas or list of nested schemas. However, you can also model the same thing as role_id: int and tags: list[int] to support IDs for linking. That’s the beauty of this extremely simple approach: it is customizable to the core.

Views#

In this example, it is easier to start with views.py:

views.py#

[source]

from http import HTTPStatus
from typing import final

from django.http import HttpResponse
from typing_extensions import override

from dmr import Body, Controller, Query, modify
from dmr.endpoint import Endpoint
from dmr.errors import ErrorType
from dmr.metadata import ResponseSpec
from dmr.pagination import Paginated
from dmr.plugins.pydantic import PydanticSerializer
from server.apps.model_fk.implemented import HasContainer
from server.apps.model_fk.serializers import (
    PageQuery,
    UserCreateSchema,
    UserSchema,
)
from server.apps.model_fk.services import (
    UniqueConstraintError,
    UserCreate,
    UserList,
)


@final
class UserController(HasContainer, Controller[PydanticSerializer]):
    def get(self, parsed_query: Query[PageQuery]) -> Paginated[UserSchema]:
        """List existing users."""
        return self.resolve(UserList)(parsed_query)

    @modify(
        extra_responses=[
            ResponseSpec(
                Controller.error_model,
                status_code=HTTPStatus.CONFLICT,
            ),
        ],
    )
    def post(self, parsed_body: Body[UserCreateSchema]) -> UserSchema:
        """Create new user."""
        return self.resolve(UserCreate)(parsed_body)

    @override
    def handle_error(
        self,
        endpoint: Endpoint,
        controller: Controller[PydanticSerializer],
        exc: Exception,
    ) -> HttpResponse:
        # Handle custom errors that can happen in this controller:
        if isinstance(exc, UniqueConstraintError):
            return self.to_error(
                self.format_error(
                    'User `email` must be unique',
                    error_type=ErrorType.value_error,
                ),
                status_code=HTTPStatus.CONFLICT,
            )
        # Handle default errors:
        return super().handle_error(endpoint, controller, exc)

Run result

$ curl http://127.0.0.1:8000/api/users/ -X POST -d '{"email": "test@example.com", "role": {"name": "admin"}, "tags": [{"name": "paid"}]}' -H 'Content-Type: application/json'
{"email":"test@example.com","role":{"name":"admin"},"tags":[{"name":"paid"}],"id":1,"created_at":"2026-10-05T11:18:09.051247Z"}

$ curl http://127.0.0.1:8000/api/users/ -X GET
{"count":1,"num_pages":1,"per_page":10,"page":{"number":1,"object_list":[{"email":"test@example.com","role":{"name":"admin"},"tags":[{"name":"paid"}],"id":1,"created_at":"2026-10-05T11:18:09.051247Z"}]}}

What happens here?

We refactored our views to only run an instance of a specific service, which we get using HasContainer.resolve call, which is our DI
We now don’t construct any serializer schemas inside our views, we move to its independent infra layer
We now use Pagination to list all users

Our views here are reduced to a single line of code, which do everything inside the business logic. Exactly the way it should be for scalable and reliable applications.

DI#

In this example we use punq as a simplistic DI container to show how big projects really handle such cases.

Note

You are not forced to use punq, we don’t enforce any DI framework. Our principle is to Bring your own DI.

The DI part looks like this:

views.py#

[source]

from typing import Any, TypeVar

import punq

from server.apps.model_fk.mappers import RoleMap, TagMap, UserMap
from server.apps.model_fk.services import (
    RoleCreate,
    TagsCreate,
    UserCreate,
    UserList,
)

_ItemT = TypeVar('_ItemT')


class HasContainer:
    __slots__ = ('_container',)

    def __init__(self, *args: Any, **kwargs: Any) -> None:
        super().__init__(*args, **kwargs)
        # Will be created in import-time:
        self._container = self._create_container()

    def resolve(self, thing: type[_ItemT]) -> _ItemT:
        return self._container.resolve(thing)

    def _create_container(self) -> punq.Container:
        container = punq.Container()
        container.register(TagMap)
        container.register(RoleMap)
        container.register(UserMap)

        container.register(TagsCreate)
        container.register(RoleCreate)
        container.register(UserCreate)
        container.register(UserList)

        return container

What happens here?

We define a class that will be used as a mixin for all future controllers
This class provides a pre-built container with all the dependencies
Users can call self.resolve inside controllers to resolve specific dependencies

Now, let’s see how we create objects in the database.

Services#

Again, this is just an example. You are not forced to create this specific service-based architecture. Use whatever layer separation practice you want. Our big example uses usecases as the main logic entities and entry points.

However, our services.py is the simplest and the shortest way. That’s why we are using them as an example:

services.py#

[source]

from collections.abc import Iterable
from typing import final

import attrs
from django.db import IntegrityError, transaction

from dmr.pagination import Paginated
from server.apps.model_fk.mappers import UserMap
from server.apps.model_fk.models import Role, Tag, User
from server.apps.model_fk.serializers import (
    PageQuery,
    RoleSchema,
    TagSchema,
    UserCreateSchema,
    UserSchema,
)


@final
class UniqueConstraintError(Exception):
    """Field ``email`` must be unique."""


@final
@attrs.define(frozen=True)
class TagsCreate:
    def __call__(self, tags: list[TagSchema]) -> Iterable[Tag]:
        """Service for creating new tags with unique names."""
        tags_names = {tag.name for tag in tags}
        # Create new tags and ignore existing ones in 1 query:
        Tag.objects.bulk_create(
            [Tag(name=tag) for tag in tags_names],
            ignore_conflicts=True,
        )
        # Since `bulk_create` does not return `ids`, we need to query them:
        return Tag.objects.in_bulk(
            tags_names,
            field_name='name',
        ).values()


@final
@attrs.define(frozen=True)
class RoleCreate:
    def __call__(self, role_schema: RoleSchema) -> Role:
        """Service for getting an existing role or creating a new one."""
        role, _ = Role.objects.get_or_create(name=role_schema.name)
        return role


@final
@attrs.define(frozen=True)
class UserCreate:
    _role_create: RoleCreate
    _tags_create: TagsCreate
    _mapper: UserMap

    def __call__(self, user_schema: UserCreateSchema) -> UserSchema:
        """Service to create new users."""
        return self._mapper.single(self._create_user(user_schema))

    def _create_user(self, user_schema: UserCreateSchema) -> User:
        with transaction.atomic():
            role = self._role_create(user_schema.role)

            try:
                user = User.objects.create(
                    email=user_schema.email,
                    role=role,
                )
            except IntegrityError:
                # We don't raise `IntegrityError` here, because we prefer domain
                # exceptions over Django ones. It is much easier to manage.
                raise UniqueConstraintError from None

            # Handle m2m:
            user.tags.set(self._tags_create(user_schema.tags))
        return user


@final
@attrs.define(frozen=True)
class UserList:
    _mapper: UserMap

    def __call__(self, parsed_query: PageQuery) -> Paginated[UserSchema]:
        """Return all users."""
        return self._mapper.multiple(
            (
                User.objects
                .select_related('role')
                .prefetch_related('tags')
                .order_by('id')
                .all()  # it is still lazy
            ),
            parsed_query,
        )

What happens here?

We define three services: one per create operation
Some of them have dependencies defined as dataclass fields, like _mapper: UserMap. These fields will be resolved by our DI.
Each service does just a single thing, it would be easy to compose them

Now we are ready for the final layer: mapping of the created database models.

Mappers#

Mappers just map database models into serialization schemas.

Tip

In real projects, it is better to have a separate layer that does mapping of database models into serialization schemas

It will allow you to compose mappers freely. For example, it allows you to create compatibility layers, when some model has some database fields removed, but you still need a way to send users the same API schema.

Or it can do some small representation logic, like combining first_name and last_name of users into full_name.

Or handle Pagination, as we do in this example.

mappers.py#

[source]

from typing import final

import attrs
from django.core.paginator import EmptyPage, Paginator
from django.db.models import QuerySet

from dmr.pagination import Page, Paginated
from server.apps.model_fk.models import Role, Tag, User
from server.apps.model_fk.serializers import (
    PageQuery,
    RoleSchema,
    TagSchema,
    UserSchema,
)


@final
@attrs.define(frozen=True)
class TagMap:
    def single(self, tag: Tag) -> TagSchema:
        return TagSchema(name=tag.name)

    def multiple(self, tags: QuerySet[Tag]) -> list[TagSchema]:
        return [self.single(tag) for tag in tags]


@final
@attrs.define(frozen=True)
class RoleMap:
    def single(self, role: Role) -> RoleSchema:
        return RoleSchema(name=role.name)


@final
@attrs.define(frozen=True)
class UserMap:
    _role: RoleMap
    _tag: TagMap

    def single(self, user: User) -> UserSchema:
        return UserSchema(
            id=user.pk,
            email=user.email,
            created_at=user.created_at,
            role=self._role.single(user.role),
            tags=self._tag.multiple(user.tags.all()),
        )

    def multiple(
        self,
        users: QuerySet[User],
        parsed_query: PageQuery,
    ) -> Paginated[UserSchema]:
        # Logic to paginate users:
        paginator = Paginator(users, parsed_query.page_size)
        try:
            object_list = [
                self.single(user)
                for user in paginator.page(parsed_query.page).object_list
            ]
        except EmptyPage:
            object_list = []
        return Paginated(
            count=paginator.count,
            num_pages=paginator.num_pages,
            per_page=paginator.per_page,
            page=Page(
                number=parsed_query.page,
                object_list=object_list,
            ),
        )

Now we have a fully working application. With composable and flexible schemas, which will:

Report any type errors early
Be customizable to the core
Can be used in a good architecture in big real business apps
Change independently from models

Conclusions#

Here’s the final table to help you decide what to use:

Your App	What to Use
Todo App	Minimalistic Example
Real Application	Mappers

django-mantle#

If you want to automate the mapping part and automagically convert QuerySet into typed models, you can use django-mantle.

Allows you to move your business logic into type-safe Python classes, decoupled from the Django ORM.
Provides automatic generation (with declarative overrides) of efficient ORM queries, including limited field fetches with only() and defer() and prefetching related objects, avoiding N+1 query problems.
Uses a modern and performant approach to serialisation and validation.
Provides a progressive API, with a minimal surface area by default, and depth when needed.

It’s your type-safe layer around Django’s liquid core.

views.py#

[source]

import attrs

from dmr import Controller
from dmr.plugins.msgspec import MsgspecSerializer


@attrs.define
class _UserModel:
    username: str
    email: str
    is_active: bool


class UsersController(Controller[MsgspecSerializer]):
    def get(self) -> list[_UserModel]:
        # We have to do import here due to how our docs build systems works,
        # but in real apps they must be on the module level:
        from django.contrib.auth.models import User  # noqa: PLC0415
        from mantle import Query  # noqa: PLC0415

        return Query(User.objects.all(), _UserModel).all()

Run result

$ curl http://127.0.0.1:8000/api/users/ -X GET
[{"email":"test@example.com","is_active":true,"username":"test_user"}]

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_UserModel": {
        "properties": {
          "email": {
            "type": "string"
          },
          "is_active": {
            "type": "boolean"
          },
          "username": {
            "type": "string"
          }
        },
        "required": [
          "username",
          "email",
          "is_active"
        ],
        "title": "_UserModel",
        "type": "object"
      }
    }
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/userscontroller/": {
      "get": {
        "operationId": "getUsersControllerApiUserscontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/_UserModel"
                  },
                  "type": "array"
                }
              }
            },
            "description": "OK"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

django-modern-schemas#

If you want to automate the schema definition part and derive your serializer schemas from the models you already have, you can use django-modern-schemas.

Generates pydantic.BaseModel subclasses from your Model definitions, reusing field types, constraints, defaults, choices and relationships, so things like max_length are declared once.
Keeps the API contract explicit: fields, exclude and optional define what a schema exposes, so read, create and PATCH schemas are built from the same model without repeating it.
Maps model methods and dotted ORM paths into schema fields with MethodSource and Source, including reverse relations, nested schemas and aggregates.
ModelSchema is generic in its model, so .create(), .update() and .save() are typed as returning that exact model.
Needs nothing in INSTALLED_APPS: schemas are regular Python classes.

From the controller’s point of view they are just pydantic schemas: QuerySet and Model instances are valid inputs, and .save() writes a parsed body back to the database. The very same schema serves a collection and a single object.

views.py#

[source]

from typing import Annotated, Final, final

import pydantic
from django.contrib.auth.models import User
from django.shortcuts import get_object_or_404
from django_modern_schemas import MethodSource, ModelSchema
from typing_extensions import TypedDict

from dmr import Body, Controller, Path
from dmr.plugins.pydantic import PydanticFastSerializer
from dmr.routing import Router, path


class UserSchema(ModelSchema[User]):
    # Extra fields can be computed by the model itself:
    full_name: Annotated[str, MethodSource('get_full_name')]

    class Config:
        model = User
        fields = ('id', 'username', 'email')


class UserCreateSchema(ModelSchema[User]):
    class Config:
        model = User
        fields = ('username', 'email', 'first_name', 'last_name')


class _UserPath(TypedDict):
    user_id: int


_UserList: Final = pydantic.TypeAdapter(list[UserSchema])


@final
class UsersController(Controller[PydanticFastSerializer]):
    def get(self) -> list[UserSchema]:
        return _UserList.validate_python(User.objects.all())

    def post(self, parsed_body: Body[UserCreateSchema]) -> UserSchema:
        # Schemas know how to persist themselves:
        return UserSchema.model_validate(parsed_body.save())


@final
class UserDetailController(Controller[PydanticFastSerializer]):
    def get(self, parsed_path: Path[_UserPath]) -> UserSchema:
        return UserSchema.model_validate(
            get_object_or_404(User, pk=parsed_path['user_id']),
        )


router = Router(
    'api/',
    [
        path('users/', UsersController.as_view(), name='users'),
        path(
            'users/<int:user_id>/',
            UserDetailController.as_view(),
            name='user',
        ),
    ],
)

urlpatterns = [router.to_urlpatterns(namespace='api')]

Run result

$ curl http://127.0.0.1:8000/api/users/ -X POST -d '{"username": "ada", "email": "ada@example.com", "first_name": "Ada", "last_name": "Lovelace"}' -H 'Content-Type: application/json'
{"id":2,"username":"ada","email":"ada@example.com","full_name":"Ada Lovelace"}

$ curl http://127.0.0.1:8000/api/users/ -X GET
[{"id":1,"username":"test_user","email":"test@example.com","full_name":""},{"id":2,"username":"ada","email":"ada@example.com","full_name":"Ada Lovelace"}]

$ curl http://127.0.0.1:8000/api/users/1/ -X GET
{"id":1,"username":"test_user","email":"test@example.com","full_name":""}

Note

Schemas generated this way follow your database tables by default. Keep fields and exclude explicit to decide what your API really exposes, as described in the sections above.