Content negotiation¶

django-modern-rest supports content negotiation.

We have two abstractions to do that:

Parsers: instances of subtypes of Parser type that parses request body based on Content-Type header into python primitives
Renderers: instances of subtypes of Renderer type that renders python primitives into a requested format based on the Accept header

By default json parser and renderer are configured to use msgspec if it is installed (recommended). We fallback to pure-python implementation if msgspec is not installed.

Supported content types¶

We ship several pre-defined parsers and renderers.

Parsers:

application/json with MsgspecJsonParser and JsonParser
application/msgpack with MsgpackParser
multipart/form-data with MultiPartParser
application/x-www-form-urlencoded with FormUrlEncodedParser

Renderers:

application/json with MsgspecJsonRenderer and JsonRenderer
application/msgpack with MsgpackRenderer
*/* with FileRenderer

You can write your own!

How parser and renderer are selected¶

We select a Parser instance if there’s a Body or FileMetadata components to parse. Otherwise, for performance reasons, no parser is selected at all. Nothing to parse - no parser is selected.

Here’s how we select a parser, when it is needed:

We look at the Content-Type header
If it is not provided, we take the default parser, which is the first specified parser for the endpoint, aka the most specific one
If there’s a Content-Type header, we try to exactly match known parsers based on their content_type attribute. This is a positive path optimization
If there’s no direct match, we now include parsers that have * pattern in supported content types. We match them in order based on 'specificity', 'quality', the first match wins
If no parser fits the request’s content type, we raise RequestSerializationError

We select Renderer instance for all responses (including error responses), before performing any logic. If the selection fails, we don’t even try to run the endpoint.

Here’s how we select a renderer:

We look at Accept header
If it is not provided, we take the default renderer, which is the first specified renderer for the endpoint, aka the most specific one
If there’s an Accept header, we use all renderers specified for this endpoint to match the best accepted type, based on quality, specificity, the first match wins
If no renderer fits for the accepted content types, we raise ResponseSchemaError

Note

When constructing responses manually, like:

>>> from django.http import HttpResponse
>>> response = HttpResponse(b'[]')

The renderer is selected as usual, but no actual rendering is done. However, all other validation works as expected. Which means that even though renderer is not actually used, its metadata is still required to validate the response content type.

But, when using to_response() method, renderer will be executed. So, it is a preferred method for regular responses.

Important

Settings always must have one parser and one renderer defined at all times, because utils like dmr.response.build_response() fallbacks to settings-defined renderers in some error cases.

Alternative JSON backends¶

By default, we use msgspec if it installed. When it is not, we fallback to JsonParser and JsonRenderer types, which use native pure Python json with limited features support and very low performance.

For users, who does not want to use msgspec, but prefer orjson for some reason, we provide the following API:

views.py¶

[source]

import orjson  # type: ignore[import-not-found, unused-ignore]
import pydantic

from dmr import Body, Controller
from dmr.parsers import JsonParser
from dmr.plugins.pydantic import PydanticSerializer
from dmr.renderers import JsonRenderer


class _UserInputData(pydantic.BaseModel):
    email: pydantic.EmailStr


class UserController(Controller[PydanticSerializer]):
    parsers = (JsonParser(json_module=orjson),)
    renderers = (JsonRenderer(json_module=orjson),)

    def post(
        self,
        parsed_body: Body[_UserInputData],
    ) -> _UserInputData:
        return parsed_body

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@example.com"}' -H 'Content-Type: application/json'
{"email":"user@example.com"}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_UserInputData": {
        "properties": {
          "email": {
            "format": "email",
            "title": "Email",
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "_UserInputData",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_UserInputData"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/_UserInputData"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "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"
          }
        }
      }
    }
  }
}

Any module that exposes API that fits JsonModule protocol is supported. If some API does not fit exactly, you can create a small wrapper that would fit, like NativeJson.

orjson is the recommended alternative because it is really fast, returns bytes directly, avoiding an extra encode step, and is significantly faster than the standard library json.

Customizing negotiation process¶

Note

If you only use json API - there’s no need to change anything.

However, if you want to support other formats like xml or custom ones, you can write and configure your own parsers and renderers.

Parsers and renderers might be defined on different levels. Here are all the possible ways starting with the most specific one, going back to the less specific:

views.py¶

[source]

import uuid
from typing import Generic, TypeVar

import pydantic

from dmr import Body, Controller, modify
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _UserProfile(pydantic.BaseModel):
    age: int


class _UserInputData(pydantic.BaseModel):
    email: str
    profile: _UserProfile


class _UserOutputData(_UserInputData):
    uid: uuid.UUID


_ModelT = TypeVar('_ModelT')


class _UserDocument(pydantic.BaseModel, Generic[_ModelT]):
    user: _ModelT


class UserController(Controller[PydanticSerializer]):
    @modify(parsers=[XmlParser()], renderers=[XmlRenderer()])
    def post(
        self,
        parsed_body: Body[_UserDocument[_UserInputData]],
    ) -> _UserDocument[_UserOutputData]:
        return _UserDocument(
            user=_UserOutputData(
                uid=uuid.uuid4(),
                email=parsed_body.user.email,
                profile=parsed_body.user.profile,
            ),
        )

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '<request><user><email>user@example.com</email><profile><age>28</age></profile></user></request>' -H 'Content-Type: application/xml' -H 'Accept: application/xml'
<?xml version="1.0" encoding="utf-8"?>
<_UserDocument><user><email>user@example.com</email><profile><age>28</age></profile><uid>9178b669-8ea6-431a-8fda-97a22c41cea9</uid></user></_UserDocument>

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_UserDocument[_UserInputData]": {
        "properties": {
          "user": {
            "$ref": "#/components/schemas/_UserInputData"
          }
        },
        "required": [
          "user"
        ],
        "title": "_UserDocument[_UserInputData]",
        "type": "object"
      },
      "_UserDocument[_UserOutputData]": {
        "properties": {
          "user": {
            "$ref": "#/components/schemas/_UserOutputData"
          }
        },
        "required": [
          "user"
        ],
        "title": "_UserDocument[_UserOutputData]",
        "type": "object"
      },
      "_UserInputData": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          },
          "profile": {
            "$ref": "#/components/schemas/_UserProfile"
          }
        },
        "required": [
          "email",
          "profile"
        ],
        "title": "_UserInputData",
        "type": "object"
      },
      "_UserOutputData": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          },
          "profile": {
            "$ref": "#/components/schemas/_UserProfile"
          },
          "uid": {
            "format": "uuid",
            "title": "Uid",
            "type": "string"
          }
        },
        "required": [
          "email",
          "profile",
          "uid"
        ],
        "title": "_UserOutputData",
        "type": "object"
      },
      "_UserProfile": {
        "properties": {
          "age": {
            "title": "Age",
            "type": "integer"
          }
        },
        "required": [
          "age"
        ],
        "title": "_UserProfile",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/_UserDocument[_UserInputData]"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_UserDocument[_UserOutputData]"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

views.py¶

[source]

import uuid
from typing import Generic, TypeVar

import pydantic

from dmr import Body, Controller
from dmr.plugins.msgspec import MsgspecJsonParser, MsgspecJsonRenderer
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _UserProfile(pydantic.BaseModel):
    age: int


class _UserInputData(pydantic.BaseModel):
    email: str
    profile: _UserProfile


class _UserOutputData(_UserInputData):
    uid: uuid.UUID


_ModelT = TypeVar('_ModelT')


class _UserDocument(pydantic.BaseModel, Generic[_ModelT]):
    user: _ModelT


class UserController(Controller[PydanticSerializer]):
    parsers = (MsgspecJsonParser(), XmlParser())
    renderers = (MsgspecJsonRenderer(), XmlRenderer())

    def post(
        self,
        parsed_body: Body[_UserDocument[_UserInputData]],
    ) -> _UserDocument[_UserOutputData]:
        return _UserDocument(
            user=_UserOutputData(
                uid=uuid.uuid4(),
                email=parsed_body.user.email,
                profile=parsed_body.user.profile,
            ),
        )

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '<request><user><email>user@example.com</email><profile><age>28</age></profile></user></request>' -H 'Content-Type: application/xml' -H 'Accept: application/json'
{"user":{"email":"user@example.com","profile":{"age":28},"uid":"75066f5d-4a3a-43df-9d47-51357408c527"}}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_UserDocument[_UserInputData]": {
        "properties": {
          "user": {
            "$ref": "#/components/schemas/_UserInputData"
          }
        },
        "required": [
          "user"
        ],
        "title": "_UserDocument[_UserInputData]",
        "type": "object"
      },
      "_UserDocument[_UserOutputData]": {
        "properties": {
          "user": {
            "$ref": "#/components/schemas/_UserOutputData"
          }
        },
        "required": [
          "user"
        ],
        "title": "_UserDocument[_UserOutputData]",
        "type": "object"
      },
      "_UserInputData": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          },
          "profile": {
            "$ref": "#/components/schemas/_UserProfile"
          }
        },
        "required": [
          "email",
          "profile"
        ],
        "title": "_UserInputData",
        "type": "object"
      },
      "_UserOutputData": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          },
          "profile": {
            "$ref": "#/components/schemas/_UserProfile"
          },
          "uid": {
            "format": "uuid",
            "title": "Uid",
            "type": "string"
          }
        },
        "required": [
          "email",
          "profile",
          "uid"
        ],
        "title": "_UserOutputData",
        "type": "object"
      },
      "_UserProfile": {
        "properties": {
          "age": {
            "title": "Age",
            "type": "integer"
          }
        },
        "required": [
          "age"
        ],
        "title": "_UserProfile",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_UserDocument[_UserInputData]"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/_UserDocument[_UserInputData]"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/_UserDocument[_UserOutputData]"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_UserDocument[_UserOutputData]"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

settings.py¶

[source]

from dmr.settings import Settings
from examples.negotiation.negotiation import XmlParser, XmlRenderer

DMR_SETTINGS = {  # noqa: WPS407
    Settings.parsers: [XmlParser()],
    Settings.renderers: [XmlRenderer()],
}

First parsers / renderers definition found, starting from the top, will win and be used for the endpoint.

You can also modify dmr.endpoint.Endpoint.request_negotiator_cls and dmr.endpoint.Endpoint.response_negotiator_cls to completely change the negotiation logic to fit your needs.

This is possible on per-controller level.

Writing custom parsers and renderers¶

And here’s how our test xml parser and renderer are defined:

negotiation.py¶

[source]

from collections.abc import Callable
from typing import Any, final
from xml.parsers import expat

import xmltodict_rs as xmltodict
from django.http import HttpRequest
from typing_extensions import override

from dmr.exceptions import DataRenderingError, RequestSerializationError
from dmr.negotiation import ContentType
from dmr.parsers import DeserializeFunc, Parser, Raw
from dmr.renderers import Renderer


@final
class XmlParser(Parser):
    __slots__ = ()

    content_type = ContentType.xml

    @override
    def parse(
        self,
        to_deserialize: Raw,
        deserializer_hook: DeserializeFunc | None = None,
        *,
        request: HttpRequest,
        model: Any,
    ) -> Any:
        try:
            parsed = xmltodict.parse(
                to_deserialize,
                process_namespaces=True,
                postprocessor=self._postprocessor,
                # TODO: this is really bad, but I have no idea what to do.
                force_list={'detail', 'loc'},
            )
        except expat.ExpatError as exc:
            raise RequestSerializationError(str(exc)) from None
        return parsed[next(iter(parsed.keys()))]

    def _postprocessor(
        self,
        path: Any,
        key: str,
        xml_value: Any,
    ) -> tuple[str, Any]:
        # xmltodict converts empty tags to `None`; for leaf fields in payloads
        # we normalize them to empty strings to match OpenAPI string semantics.
        if xml_value is None:
            return key, ''
        return key, xml_value


@final
class XmlRenderer(Renderer):
    __slots__ = ()

    content_type = ContentType.xml

    @override
    def render(
        self,
        to_serialize: Any,
        serializer_hook: Callable[[Any], Any],
    ) -> bytes:
        preprocessor = self._wrap_serializer(serializer_hook)
        raw_data = xmltodict.unparse(
            {type(to_serialize).__qualname__: to_serialize},
            preprocessor=preprocessor,
        )
        assert isinstance(raw_data, str)
        return raw_data.encode('utf8')

    @property
    @override
    def validation_parser(self) -> XmlParser:
        return XmlParser()

    def _wrap_serializer(
        self,
        serializer_hook: Callable[[Any], Any],
    ) -> Callable[[str, Any], tuple[str, Any]]:
        def factory(xml_key: str, xml_value: Any) -> tuple[str, Any]:
            try:  # noqa: SIM105
                xml_value = serializer_hook(xml_value)
            except DataRenderingError:
                pass  # noqa: WPS420
            return xml_key, xml_value

        return factory

Warning

This parser is only used as a demo, do not use it in production, prefer more tested and battle-proven solutions.

Using different schemes for different content types¶

Sometimes we have to accept different schemas based on the content type. According to the OpenAPI spec, Body should support different content types.

We utilize typing.Annotated and dmr.negotiation.conditional_type():

views.py¶

[source]

from typing import Annotated

import pydantic

from dmr import Body, Controller
from dmr.negotiation import ContentType, conditional_type
from dmr.plugins.msgspec import MsgspecJsonParser, MsgspecJsonRenderer
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _XMLRequestModel(pydantic.BaseModel):
    root: dict[str, str]


class ExampleController(
    Controller[PydanticSerializer],
):
    parsers = (MsgspecJsonParser(), XmlParser())
    renderers = (MsgspecJsonRenderer(), XmlRenderer())

    def post(
        self,
        parsed_body: Body[
            Annotated[
                # The body will be a union of these two types:
                _XMLRequestModel | dict[str, str],
                conditional_type({
                    # But, for json it will always be:
                    ContentType.json: dict[str, str],
                    # And for xml it will always be:
                    ContentType.xml: _XMLRequestModel,
                }),
            ],
        ],
    ) -> dict[str, str]:
        if isinstance(parsed_body, _XMLRequestModel):
            return parsed_body.root
        return parsed_body

Run result

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '<request><root><one>first</one></root></request>' -H 'Content-Type: application/xml' -H 'Accept: application/xml'
<?xml version="1.0" encoding="utf-8"?>
<dict><one>first</one></dict>

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '{"one": "first"}' -H 'Content-Type: application/json' -H 'Accept: application/json'
{"one":"first"}

$ curl http://127.0.0.1:8000/api/example/ -D - -X POST -d '{"root": {"mixin-json-content-type": "with-xml-format"}}' -H 'Content-Type: application/json' -H 'Accept: application/json'
HTTP/1.1 400 Bad Request
date: Thu, 07 May 2026 12:58:05 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 103
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Input should be a valid string","loc":["parsed_body","root"],"type":"value_error"}]}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_XMLRequestModel": {
        "properties": {
          "root": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Root",
            "type": "object"
          }
        },
        "required": [
          "root"
        ],
        "title": "_XMLRequestModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/examplecontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postExamplecontrollerApiExamplecontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/_XMLRequestModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              },
              "application/xml": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

We strictly validate that each content type will have its own unique model. As the last example shows, it is impossible to send _XMLRequestModel with Content-Type: application/json header.

The same works for return types as well:

views.py¶

[source]

from typing import Annotated

import pydantic

from dmr import Body, Controller
from dmr.negotiation import ContentType, conditional_type
from dmr.plugins.msgspec import MsgspecJsonParser, MsgspecJsonRenderer
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _RequestModel(pydantic.BaseModel):
    root: dict[str, str]


class ExampleController(
    Controller[PydanticSerializer],
):
    parsers = (MsgspecJsonParser(), XmlParser())
    renderers = (MsgspecJsonRenderer(), XmlRenderer())

    def post(
        self,
        parsed_body: Body[_RequestModel],
    ) -> Annotated[
        dict[str, str] | list[str],
        conditional_type({
            ContentType.json: list[str],
            ContentType.xml: dict[str, str],
        }),
    ]:
        if self.request.accepts(ContentType.json):
            return list(parsed_body.root.values())
        return parsed_body.root

Run result

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '<request><root><one>first</one></root></request>' -H 'Content-Type: application/xml' -H 'Accept: application/xml'
<?xml version="1.0" encoding="utf-8"?>
<dict><one>first</one></dict>

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '{"root": {"one": "first"}}' -H 'Content-Type: application/json' -H 'Accept: application/json'
["first"]

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_RequestModel": {
        "properties": {
          "root": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Root",
            "type": "object"
          }
        },
        "required": [
          "root"
        ],
        "title": "_RequestModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/examplecontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postExamplecontrollerApiExamplecontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_RequestModel"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/_RequestModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "application/xml": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Depending on the content type - your return schema will be fully validated as well. In the example above, it would be an error to return something other than list[str] for json content type, and it would also be an error to return anything other than dict[str, str] for xml content type.

You can combine conditional bodies and conditional return types in a type-safe and fully OpenAPI-compatible way.

Using different error models for different content types¶

The same can be done with error models. Let’s say you want to present JSON and XML error models differently.

We utilize the same technique typing.Annotated and dmr.negotiation.conditional_type():

views.py¶

[source]

from typing import Annotated, TypedDict

import pydantic
from typing_extensions import override

from dmr import Body, Controller
from dmr.errors import ErrorModel, ErrorType
from dmr.negotiation import ContentType, conditional_type
from dmr.plugins.msgspec import MsgspecJsonRenderer
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlRenderer


class _RequestModel(pydantic.BaseModel):
    root: dict[str, str]


class _CustomXmlErrorModel(TypedDict):
    xml_errors: dict[str, str]


class ExampleController(
    Controller[PydanticSerializer],
):
    renderers = (MsgspecJsonRenderer(), XmlRenderer())
    error_model = Annotated[
        ErrorModel | _CustomXmlErrorModel,
        conditional_type({
            ContentType.json: ErrorModel,
            ContentType.xml: _CustomXmlErrorModel,
        }),
    ]

    def post(self, parsed_body: Body[_RequestModel]) -> str:
        # Will not be called in this example, because we fail to parse body:
        raise NotImplementedError

    @override
    def format_error(
        self,
        error: str | Exception,
        *,
        loc: str | list[str | int] | None = None,
        error_type: str | ErrorType | None = None,
    ) -> ErrorModel | _CustomXmlErrorModel:
        original: ErrorModel = super().format_error(
            error,
            loc=loc,
            error_type=error_type,
        )
        if self.request.accepts(ContentType.json):
            return original
        return {
            'xml_errors': {
                '.'.join(str(location) for location in detail['loc']): detail[
                    'msg'
                ]
                for detail in original['detail']
            },
        }

Run result

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '{}' -H 'Content-Type: application/json' -H 'Accept: application/json'
{"detail":[{"msg":"Field required","loc":["parsed_body","root"],"type":"value_error"}]}

$ curl http://127.0.0.1:8000/api/example/ -X POST -d '{}' -H 'Content-Type: application/json' -H 'Accept: application/xml'
<?xml version="1.0" encoding="utf-8"?>
<dict><xml_errors><parsed_body.root>Field required</parsed_body.root></xml_errors></dict>

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_CustomXmlErrorModel": {
        "properties": {
          "xml_errors": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Xml Errors",
            "type": "object"
          }
        },
        "required": [
          "xml_errors"
        ],
        "title": "_CustomXmlErrorModel",
        "type": "object"
      },
      "_RequestModel": {
        "properties": {
          "root": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Root",
            "type": "object"
          }
        },
        "required": [
          "root"
        ],
        "title": "_RequestModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/examplecontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postExamplecontrollerApiExamplecontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_RequestModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_CustomXmlErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_CustomXmlErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_CustomXmlErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Note that you would also have to customize format_error() accordingly.

Limiting response specs to content types¶

Sometimes some responses can only be returned for some content types. We need a way to describe it: both for our validation and OpenAPI spec.

To do so, we utilize limit_to_content_types attribute:

views.py¶

[source]

from http import HTTPStatus

import pydantic

from dmr import APIError, Controller, Query, ResponseSpec
from dmr.negotiation import ContentType
from dmr.plugins.msgspec import MsgspecJsonParser, MsgspecJsonRenderer
from dmr.plugins.pydantic import PydanticSerializer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _QueryModel(pydantic.BaseModel):
    show_error: bool = False


class ExampleController(Controller[PydanticSerializer]):
    parsers = (MsgspecJsonParser(), XmlParser())
    renderers = (MsgspecJsonRenderer(), XmlRenderer())
    responses = (
        ResponseSpec(
            list[str],
            status_code=HTTPStatus.CONFLICT,
            limit_to_content_types={ContentType.json},
        ),
        ResponseSpec(
            dict[str, str],
            status_code=HTTPStatus.PAYMENT_REQUIRED,
            limit_to_content_types={ContentType.xml},
        ),
    )

    def get(self, parsed_query: Query[_QueryModel]) -> str:
        if self.request.accepts(ContentType.json):
            if parsed_query.show_error:
                # This is explicitly wrong:
                # `PAYMENT_REQUIRED` cannot happen with `json`,
                # response validation will catch this:
                raise APIError([], status_code=HTTPStatus.PAYMENT_REQUIRED)
            raise APIError(['wrong', 'items'], status_code=HTTPStatus.CONFLICT)
        raise APIError(
            {'wrong': 'items'},
            status_code=HTTPStatus.PAYMENT_REQUIRED,
        )

Run result

$ curl http://127.0.0.1:8000/api/example/ -X GET -H 'Accept: application/json'
["wrong","items"]

$ curl http://127.0.0.1:8000/api/example/ -X GET -H 'Accept: application/xml'
<?xml version="1.0" encoding="utf-8"?>
<dict><wrong>items</wrong></dict>

$ curl 'http://127.0.0.1:8000/api/example/?show_error=1' -D - -X GET -H 'Accept: application/json'
HTTP/1.1 422 Unprocessable Entity
date: Thu, 07 May 2026 12:58:08 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 124
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Response 402 is not allowed for 'application/json', only for ['application/xml']","type":"value_error"}]}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "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"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/examplecontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getExamplecontrollerApiExamplecontroller",
        "parameters": [
          {
            "deprecated": false,
            "in": "query",
            "name": "show_error",
            "schema": {
              "default": false,
              "title": "Show Error",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "402": {
            "content": {
              "application/xml": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment Required"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Conflict"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

Disabling content negotiation validation¶

When validate_responses is active, we also validate that the returned Content-Type header matches the negotiated content type.

To disable this validation, if you for some reason, want to break the content negotiation protocol, you can set validate_negotiation to False.

We support several layers of configuration:

views.py¶

[source]

from http import HTTPStatus
from typing import TypedDict

from django.http import JsonResponse

from dmr import Body, Controller, ResponseSpec, validate
from dmr.plugins.msgspec import MsgspecSerializer
from dmr.settings import default_parser, default_renderer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _UserInputData(TypedDict):
    email: str


class UserController(Controller[MsgspecSerializer]):
    parsers = (XmlParser(), default_parser)
    renderers = (XmlRenderer(), default_renderer)

    @validate(
        ResponseSpec(_UserInputData, status_code=HTTPStatus.OK),
        validate_negotiation=False,
    )
    def post(self, parsed_body: Body[_UserInputData]) -> JsonResponse:
        # NOTE: do not do this!
        return JsonResponse(parsed_body)

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '<request><email>user@example.com</email></request>' -H 'Content-Type: application/xml' -H 'Accept: application/xml'
{"email": "user@example.com"}

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"
      },
      "_UserInputData": {
        "properties": {
          "email": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "_UserInputData",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_UserInputData"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/_UserInputData"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/_UserInputData"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_UserInputData"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

views.py¶

[source]

from http import HTTPStatus
from typing import TypedDict

from django.http import JsonResponse

from dmr import Body, Controller, ResponseSpec, validate
from dmr.plugins.msgspec import MsgspecSerializer
from dmr.settings import default_parser, default_renderer
from examples.negotiation.negotiation import XmlParser, XmlRenderer


class _UserInputData(TypedDict):
    email: str


class UserController(Controller[MsgspecSerializer]):
    parsers = (XmlParser(), default_parser)
    renderers = (XmlRenderer(), default_renderer)
    validate_negotiation = False

    @validate(ResponseSpec(_UserInputData, status_code=HTTPStatus.OK))
    def post(self, parsed_body: Body[_UserInputData]) -> JsonResponse:
        # NOTE: do not do this!
        return JsonResponse(parsed_body)

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '<request><email>user@example.com</email></request>' -H 'Content-Type: application/xml' -H 'Accept: application/xml'
{"email": "user@example.com"}

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"
      },
      "_UserInputData": {
        "properties": {
          "email": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "_UserInputData",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_UserInputData"
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/_UserInputData"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/_UserInputData"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/_UserInputData"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

settings.py¶

[source]

from dmr.settings import Settings, default_parser, default_renderer
from examples.negotiation.negotiation import XmlParser, XmlRenderer

DMR_SETTINGS = {  # noqa: WPS407
    Settings.parsers: [XmlParser(), default_parser],
    Settings.renderers: [XmlRenderer(), default_renderer],
    Settings.validate_negotiation: False,
}

Despite the fact that Content-Type is not validated, we still validate the response schema. So, you must still provide correct renderers and parsers to do validation. Otherwise, you would have to also disable Response validation.

Warning

We do not ever recommend to do this in any sane setups. This only makes sense for legacy API contracts that you want to migrate to django-modern-rest.

Negotiation API¶

class dmr.negotiation.RequestNegotiator(metadata: EndpointMetadata, serializer: type[BaseSerializer])[source]¶

Selects a correct parser type for a request.

__call__(request: HttpRequest) → Parser[source]¶

Negotiates which parser to use for parsing this request.

Based on Content-Type header.

Called in runtime. Must work for O(1) for the best case scenario because of that.

Must set __dmr_parser__ request attribute if the negotiation is successful.

Returns:: Parser class for this request.
Raises:: RequestSerializationError – when Content-Type request header is not supported.

class dmr.negotiation.ResponseNegotiator(metadata: EndpointMetadata, serializer: type[BaseSerializer], *, streaming: bool)[source]¶

Selects a correct renderer for a response body.

Changed in version 0.5.0: Now it uses a custom algorithm that is x30 times faster (when compiled with mypyc compilation) then the original django.http.HttpRequest.get_preferred_type() way we used before.

__call__(request: HttpRequest) → Renderer[source]¶

Negotiates which renderer to use for rendering this response.

Based on Accept header.

Called in runtime. Must work for O(1) because of that.

We use django.http.HttpRequest.get_preferred_type() inside. So, we have exactly the same negotiation rules as django has.

Must set __dmr_renderer__ request attribute if the negotiation is successful. Can set __dmr_nonstreaming_renderer__ if working with streaming responses.

Returns:: Renderer class for this response.
Raises:: NotAcceptableError – when Accept request header is not supported.

final class dmr.negotiation.ContentType(*values)[source]¶

Enumeration of frequently used content types.

json¶: 'application/json' format.

xml¶: 'application/xml' format.

x_www_form_urlencoded¶: 'application/x-www-form-urlencoded' format.

multipart_form_data¶: 'multipart/form-data' format.

msgpack¶: 'application/msgpack' format.

event_stream¶: 'text/event-stream' format for SSE streaming.

jsonl¶: 'application/jsonl' format for JSON Lines streaming.

json_problem_details¶: 'application/problem+json' format for RFC 9457.

dmr.negotiation.conditional_type(mapping: Mapping[str | ContentType, Any]) → ConditionalType[source]¶

Create conditional validation for different content types.

It is rather usual to see a requirement like: - If this method returns json then we should follow schema1 - If this methods returns xml then we should follow schema2

dmr.negotiation.request_parser(request: HttpRequest, *, strict: Literal[True]) → Parser[source]¶

dmr.negotiation.request_parser(request: HttpRequest, *, strict: bool = False) → Parser | None

Get parser used to parse this request.

When strict is passed and request has no parser, we raise AttributeError.

Note

Since request parsing is only used when there’s a dmr.components.Body or similar component, there might be no parser at all.

dmr.negotiation.request_renderer(request: HttpRequest, *, strict: Literal[True], use_nonstreaming_renderer: bool = False) → Renderer[source]¶

dmr.negotiation.request_renderer(request: HttpRequest, *, strict: bool = False, use_nonstreaming_renderer: bool = False) → Renderer | None

Get pre-negotiated renderer.

First, tries a special __dmr_nonstreaming_renderer__ case, which will be different for streaming responses. For example: for SSE controllers __dmr_nonstreaming_renderer__ will be just json or xml. It is not used for REST endpoints.

While __dmr_renderer__ will be whatever Accept header contains as the first value.

When strict is passed and request has no renderer, we raise AttributeError.

Note

There might not be a response renderer that fits what client has asked. So, it can return None.

dmr.negotiation.get_conditional_types(model: Any, model_meta: tuple[Any, ...]) → Mapping[str, Any] | None[source]¶

Returns possible conditional types.

Conditional types are defined with typing.Annotated and dmr.negotiation.conditional_type() helper.

Parser API¶

class dmr.parsers.Parser[source]¶

Base class for all parsers.

Subclass it to implement your own parsers.

content_type: str¶

Content-Type that this parser works with.

Must be defined for all subclasses.

abstractmethod parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → Any[source]¶

Deserialize a raw string/bytes/bytearray into an object.

Parameters:

to_deserialize – Value to deserialize.
deserializer_hook – Hook to convert types that are not natively supported.
request – Django’s original request with all the details.
model – Model that represents the final result’s structure.

Returns:

Simple python object with primitive parts.

Raises:

DataParsingError – If error decoding obj.

provide_response_specs(metadata: EndpointMetadata, controller_cls: type[Controller[BaseSerializer]], existing_responses: Mapping[HTTPStatus, ResponseSpec]) → list[ResponseSpec][source]¶: Provides responses that can happen when data can’t be parsed.

Renderer API¶

class dmr.renderers.Renderer[source]¶

Base class for all renderer types.

Subclass it to implement your own renderers.

content_type: str¶

Content-Type that this renderer works with.

Must be defined for all subclasses.

provide_response_specs(metadata: EndpointMetadata, controller_cls: type[Controller[BaseSerializer]], existing_responses: Mapping[HTTPStatus, ResponseSpec]) → list[ResponseSpec][source]¶: Provides responses that can happen when data can’t be rendered.

abstractmethod render(to_serialize: Any, serializer_hook: Callable[[Any], Any]) → bytes[source]¶: Function to be called on object serialization.

streaming: ClassVar[bool] = False¶: Whether or not this renderer is used for streaming responses.

abstract property validation_parser: Parser¶

Returns a parser that can parse what this renderer rendered.

Why? Because when validate_responses is True, we parse the response body once again to see if it fits the schema.

That’s why all renderers must know how to unparse its results.

Existing parsers and renderers¶

Parsers¶

class dmr.plugins.msgspec.MsgspecJsonParser[source]¶

Parsers json bodies using msgspec.

content_type: str = 'application/json'¶

Content-Type that this parser works with.

Must be defined for all subclasses.

parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → Any[source]¶

Deserialize a raw JSON string/bytes/bytearray into an object.

Parameters:

to_deserialize – Value to deserialize.
deserializer_hook – Hook to convert types that are not natively supported.
request – Django’s original request with all the details.
model – Model that represents the final result’s structure.

Returns:

Simple python object with primitive parts.

Raises:

DataParsingError – If error decoding obj.

class dmr.plugins.msgspec.MsgpackParser[source]¶

Parsers msgpack bodies using msgspec.

content_type: str = 'application/msgpack'¶

Content-Type that this parser works with.

Must be defined for all subclasses.

parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → Any[source]¶

Deserialize a raw msgpack string/bytes/bytearray into an object.

Parameters:

to_deserialize – Value to deserialize.
deserializer_hook – Hook to convert types that are not natively supported.
request – Django’s original request with all the details.
model – Model that represents the final result’s structure.

Returns:

Simple python object with primitive parts.

Raises:

DataParsingError – If error decoding obj.

class dmr.parsers.JsonParser(content_type: str = 'application/json', *, json_module: JsonModule = <class 'dmr.internal.json.NativeJson'>)[source]¶

Fallback implementation of a json parser.

Only is used when msgspec is not installed.

Warning

It is not recommended to be used directly when using default json module. It is slow and has less features. We won’t add any complex objects support to this parser.

Alternative json implementations can be provided. See Alternative JSON backends for more info.

content_type: str¶

Content-Type that this parser works with.

Must be defined for all subclasses.

parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → Any[source]¶

Decode a JSON string/bytes/bytearray into an object.

Parameters:

to_deserialize – Value to decode.
deserializer_hook – Hook to convert types that are not natively supported.
request – Django’s original request with all the details.
model – Model that represents the final result’s structure.

Returns:

Decoded object.

Raises:

DataParsingError – If error decoding obj.

class dmr.parsers.MultiPartParser[source]¶

Parses multipart form data.

In reality this is a quite tricky parser. Since, Django already parses multipart/form-data content natively, there’s no reason to duplicate its work. So, we return original Django’s content.

content_type: str = 'multipart/form-data'¶: Works with multipart data.

parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → None[source]¶: Returns parsed multipart form data.

class dmr.parsers.FormUrlEncodedParser[source]¶

Parses www urlencoded forms.

In reality this is a quite tricky parser. Since, Django already parses application/x-www-form-urlencoded content natively, there’s no reason to duplicate its work. So, we return original Django’s content.

content_type: str = 'application/x-www-form-urlencoded'¶: Works with urlencoded forms.

parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → None[source]¶: Returns parsed form data.

Renderers¶

class dmr.plugins.msgspec.MsgspecJsonRenderer(content_type: str = 'application/json')[source]¶

Renders json bodies using msgspec.

content_type: str¶

Content-Type that this renderer works with.

Must be defined for all subclasses.

render(to_serialize: Any, serializer_hook: Callable[[Any], Any] | None = None) → bytes[source]¶

Encode a value into JSON bytestring.

Parameters:

to_serialize – Value to encode.
serializer_hook – Callable to support non-natively supported types.

Returns:

JSON as bytes.

property validation_parser: MsgspecJsonParser¶: Msgspec can parse this.

class dmr.plugins.msgspec.MsgpackRenderer[source]¶

Renders msgpack bodies using msgspec.

content_type: str = 'application/msgpack'¶

Content-Type that this renderer works with.

Must be defined for all subclasses.

render(to_serialize: Any, serializer_hook: Callable[[Any], Any] | None = None) → bytes[source]¶

Encode a value into msgpack bytestring.

Parameters:

to_serialize – Value to encode.
serializer_hook – Callable to support non-natively supported types.

Returns:

msgpack as bytes.

property validation_parser: MsgpackParser¶: Msgspec can parse this.

class dmr.renderers.JsonRenderer(content_type: str = 'application/json', *, json_module: JsonModule = <class 'dmr.internal.json.NativeJson'>)[source]¶

Fallback implementation of a json renderer.

Only is used when msgspec is not installed.

Warning

It is not recommended to be used directly. It is slow and has less features. We won’t add any complex objects support to this renderer.

Alternative json implementations can be provided. See Alternative JSON backends for more info.

content_type: str¶

Content-Type that this renderer works with.

Must be defined for all subclasses.

render(to_serialize: Any, serializer_hook: Callable[[Any], Any]) → bytes[source]¶

Encode a value into JSON bytestring.

Parameters:

to_serialize – Value to encode.
serializer_hook – Callable to support non-natively supported types.

Returns:

JSON as bytes.

property validation_parser: JsonParser¶: Regular json parser can parse this.

class dmr.renderers.FileRenderer(content_type: str = '*/*')[source]¶

Renders any file.

Works with any files and any content types.

Warning

Works with any content type by default, so it must be an only renderer for the endpoint.

content_type: str¶

Content-Type that this renderer works with.

Must be defined for all subclasses.

render(to_serialize: Any, serializer_hook: Callable[[Any], Any]) → bytes[source]¶: Render a file.

property validation_parser: _NoOpParser¶: Since there’s nothing to parse, we return a no-op.

Advanced API¶

class dmr.parsers.SupportsFileParsing[source]¶

Mixin class for parsers that can parse files.

We require parsers that can parse files to populate django.http.HttpRequest.FILES and to not return anything.

abstractmethod parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → None[source]¶: Populate request.FILES if possible.

class dmr.parsers.SupportsDjangoDefaultParsing[source]¶

Mark for parsers that support default Django’s parsing.

By default Django can parse multipart/form-data and application/x-www-form-urlencoded in a very specific way. Django only parses django.http.HttpRequest.POST and django.http.HttpRequest.FILES when it receives a real POST request. Which does not really work for us. We need more methods to be able to send the same content.

So, parsers that extends this type must: 1. Return default parsed objects when method is POST 2. Parse similar HTTP methods the same way Django does for POST

Contract: parse() method must return None, but populate django.http.HttpRequest.POST and django.http.HttpRequest.FILES if they were missing.

abstractmethod parse(to_deserialize: bytes | bytearray, deserializer_hook: Callable[[type[Any], Any], Any] | None = None, *, request: HttpRequest, model: Any) → None[source]¶: Populate request.POST and request.FILES if possible.