Response validation¶

By default, all responses are validated at runtime to match the schema. This allows us to be super strict about schema generation as a pro, but as a con, it is slower than can possibly be.

You can disable response validation via configuration:

Warning

Disabling response validation makes sense only in production for better performance.

It is not recommended to disable response validation for any other reason. Instead, fix your schema errors!

views.py¶

[source]

from http import HTTPStatus

import msgspec

from dmr import APIError, Body, Controller, Headers
from dmr.errors import ErrorType
from dmr.plugins.msgspec import MsgspecSerializer


class UserModel(msgspec.Struct):
    email: str


class HeaderModel(msgspec.Struct):
    consumer: str = msgspec.field(name='X-API-Consumer')


class UserController(
    Controller[MsgspecSerializer],
):
    def post(
        self,
        parsed_body: Body[UserModel],
        parsed_headers: Headers[HeaderModel],
    ) -> UserModel:
        if parsed_headers.consumer != 'my-api':
            # Notice that this response is never documented in the spec,
            # so, it will raise an error when validation is enabled (default).
            raise APIError(
                self.format_error(
                    'Wrong API consumer',
                    error_type=ErrorType.user_msg,
                ),
                status_code=HTTPStatus.PAYMENT_REQUIRED,
            )
        # This response will be documented by default:
        return parsed_body

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: my-api'
{"email":"user@wms.org"}

$ curl http://127.0.0.1:8000/api/user/ -D - -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: not-my-api'
HTTP/1.1 422 Unprocessable Entity
date: Sun, 29 Mar 2026 18:53:32 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 143
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Returned status code 402 is not specified in the list of allowed status codes: [201, 400, 422, 406]","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"
                }
              ]
            },
            "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"
          }
        },
        "required": [
          "email"
        ],
        "title": "UserModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/usercontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postUsercontrollerApiUsercontroller",
        "parameters": [
          {
            "deprecated": false,
            "in": "header",
            "name": "X-API-Consumer",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserModel"
                }
              }
            },
            "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"
          }
        }
      }
    }
  }
}

views.py¶

[source]

from http import HTTPStatus

import msgspec

from dmr import APIError, Body, Controller, Headers, modify
from dmr.errors import ErrorType
from dmr.plugins.msgspec import MsgspecSerializer


class UserModel(msgspec.Struct):
    email: str


class HeaderModel(msgspec.Struct):
    consumer: str = msgspec.field(name='X-API-Consumer')


class UserController(
    Controller[MsgspecSerializer],
):
    @modify(validate_responses=False)  # <- now, we won't validate this endpoint
    def post(
        self,
        parsed_body: Body[UserModel],
        parsed_headers: Headers[HeaderModel],
    ) -> UserModel:
        if parsed_headers.consumer != 'my-api':
            # Notice that this response is never documented in the spec,
            # but, it won't raise a validation error, because validation is off
            raise APIError(
                self.format_error(
                    'Wrong API consumer',
                    error_type=ErrorType.user_msg,
                ),
                status_code=HTTPStatus.PAYMENT_REQUIRED,
            )
        # This response will be documented by default:
        return parsed_body

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: my-api'
{"email":"user@wms.org"}

$ curl http://127.0.0.1:8000/api/user/ -D - -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: not-my-api'
HTTP/1.1 402 Payment Required
date: Sun, 29 Mar 2026 18:53:33 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 59
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Wrong API consumer","type":"user_msg"}]}

views.py¶

[source]

from http import HTTPStatus

import msgspec

from dmr import APIError, Body, Controller, Headers
from dmr.errors import ErrorType
from dmr.plugins.msgspec import MsgspecSerializer


class UserModel(msgspec.Struct):
    email: str


class HeaderModel(msgspec.Struct):
    consumer: str = msgspec.field(name='X-API-Consumer')


class UserController(
    Controller[MsgspecSerializer],
):
    # Now, we won't validate all endpoints in this controller:
    validate_responses = False

    def post(
        self,
        parsed_body: Body[UserModel],
        parsed_headers: Headers[HeaderModel],
    ) -> UserModel:
        if parsed_headers.consumer != 'my-api':
            # Notice that this response is never documented in the spec,
            # but, it won't raise a validation error, because validation is off
            raise APIError(
                self.format_error(
                    'Wrong API consumer',
                    error_type=ErrorType.user_msg,
                ),
                status_code=HTTPStatus.PAYMENT_REQUIRED,
            )
        # This response will be documented by default:
        return parsed_body

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: my-api'
{"email":"user@wms.org"}

$ curl http://127.0.0.1:8000/api/user/ -D - -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: not-my-api'
HTTP/1.1 402 Payment Required
date: Sun, 29 Mar 2026 18:53:34 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 59
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Wrong API consumer","type":"user_msg"}]}

settings.py¶

>>> from dmr.settings import Settings
>>> DMR_SETTINGS = {Settings.validate_responses: False}

The “right way” is not to disable the validation, but to specify the correct schema to be returned from an endpoint.

views.py¶

[source]

from http import HTTPStatus

import msgspec

from dmr import APIError, Body, Controller, Headers, ResponseSpec, modify
from dmr.errors import ErrorModel, ErrorType
from dmr.plugins.msgspec import MsgspecSerializer


class UserModel(msgspec.Struct):
    email: str


class HeaderModel(msgspec.Struct):
    consumer: str = msgspec.field(name='X-API-Consumer')


class UserController(
    Controller[MsgspecSerializer],
):
    @modify(
        extra_responses=[
            ResponseSpec(
                ErrorModel,
                status_code=HTTPStatus.PAYMENT_REQUIRED,
            ),
        ],
    )
    def post(
        self,
        parsed_body: Body[UserModel],
        parsed_headers: Headers[HeaderModel],
    ) -> UserModel:
        if parsed_headers.consumer != 'my-api':
            # Notice that this response is now documented in the spec,
            # no error will happen, no need to disable the validation.
            raise APIError(
                self.format_error(
                    'Wrong API consumer',
                    error_type=ErrorType.user_msg,
                ),
                status_code=HTTPStatus.PAYMENT_REQUIRED,
            )
        # This response will be documented by default:
        return parsed_body

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: my-api'
{"email":"user@wms.org"}

$ curl http://127.0.0.1:8000/api/user/ -D - -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: not-my-api'
HTTP/1.1 402 Payment Required
date: Sun, 29 Mar 2026 18:53:34 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 59
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Wrong API consumer","type":"user_msg"}]}