Quart-Schema

0.23.0 verified Mon Apr 27 auth: no python

A Quart extension providing request/response schema validation using Pydantic models and OpenAPI documentation generation. Current version 0.23.0, compatible with Python >=3.10. Actively maintained, with regular releases.

pip install quart-schema

Common errors

error pydantic.errors.PydanticUserError: A custom validator cannot be used with `@validate_request` because the model is not instantiated. ↓

cause Using Pydantic validators that rely on instance state (e.g., `@validator('field', pre=True)`) that expect the model to be instantiated. `@validate_request` only validates JSON payload without model instantiation.

fix

Use @validate_request(SomeModel) and rely on Pydantic field types; avoid @validator that expects instance. If needed, manually instantiate inside the handler.

error AttributeError: module 'quart_schema' has no attribute 'QuartSchema' ↓

cause Older version of quart-schema (<0.14.0) used a different class name or not installed at all.

fix

Upgrade to latest: pip install --upgrade quart-schema.

error TypeError: 'DummyRequest' object is not subscriptable ↓

cause Trying to access `request.json` or `request.args` directly inside a function decorated with `@validate_request` before calling `await request.get_json()`. The request body is already validated and available as the argument of the function, but raw access may cause issues.

fix

Remove manual request.get_json(); the validated model is passed as a function argument automatically.

error quart.exceptions.BadRequest: 400 Bad Request: JSON decode error ↓

cause Submitting empty body or invalid JSON. `@validate_request` requires a JSON body.

fix

Ensure the client sends a valid JSON payload.

Warnings

breaking Version 0.20.0 dropped support for Python 3.7 and 3.8. Requires Python >=3.10. ↓

fix Upgrade to Python 3.10+.

deprecated The `QuartSchema` constructor parameter `convert_errors` is deprecated; use `error_handler` instead. ↓

fix Remove `convert_errors=True` and define a custom error handler via `app.error_handler` or pass `error_handler` to `QuartSchema`.

gotcha `@validate_request` expects a Pydantic model class, not an instance. Passing an instance will raise a `TypeError`. ↓

fix Decorate with `@validate_request(SomeModel)` not `@validate_request(SomeModel())`.

gotcha The `openapi_spec` blueprint must be registered manually if you want OpenAPI docs at a specific path. By default, it is mounted at `/openapi.json`. ↓

fix Use `app.register_blueprint(openapi_spec)` without arguments to get default path, or pass `url_prefix` to customize.

Imports

QuartSchema
wrong
```
from quart_schema import QuartSchema as QS
```
correct
```
from quart_schema import QuartSchema
```
Aliasing not needed, but acceptable. Common mistake: importing from wrong package (e.g., 'quart_schema' vs 'quart_schema.core')
validate_request
wrong
```
from quart_schema.decorators import validate_request
```
correct
```
from quart_schema import validate_request
```
Exposed from top-level package; internal module path may break in future versions.

openapi_spec

wrong

from quart_schema.openapi import spec

correct

from quart_schema import openapi_spec

The public symbol is `openapi_spec` at package root.

Quickstart

Minimal Quart app with request body validation using Pydantic model.

from quart import Quart, request, jsonify
from quart_schema import QuartSchema, validate_request
from pydantic import BaseModel

app = Quart(__name__)
QuartSchema(app)

class Item(BaseModel):
    name: str
    price: float

@app.route('/item', methods=['POST'])
@validate_request(Item)
async def create_item():
    data = await request.get_json()
    # data is validated as Item
    return jsonify({"created": data.name}), 201

if __name__ == '__main__':
    app.run()