[BUG] filter with list type alias fails to parse

Author: Roang-zero1Created Apr 21, 2026Updated May 10, 2026

Summary

When using a type alias for a list[*] types that is later used in a FilterSchema, the query parameter fails to parse with the error following error:

json

{
  "detail": [{
    "type": "list_type",
    "loc": ["query", "name"],
    "msg": "Input should be a valid list"
  }]
}

If the type keyword is removed, the query parameter is parsed correctly into a list.

This is not the case for non list types such as str.

Minimal viable reproduction

python

# Book is a arbitrary example Django model
from typing import Annotated
from ninja import NinjaAPI, Query
from ninja import ModelSchema
from ninja import FilterSchema, FilterLookup, Field

api = NinjaAPI()


type name_list = Annotated[list[str] | None, FilterLookup("name__in")]


class BookSchema(ModelSchema):
    class Meta:
        model = Book
        fields = "__all__"


class BookFilter(FilterSchema):
    name: name_list = Field(
        default=None,
        description="Filter by name, multiple values allowed",
        examples=["Title 1", "How to Ninja"],
    )


@api.get("/books", response=list[BookSchema])
def api_list(request, filters: Query[BookFilter]):
    objects = Book.objects.all()
    objects = filters.filter(objects)
    return list(objects)

bash

curl -G -d "name=Test" -d "name=Test%201" http://localhost:8000/api/books

Further tests

python

name_list = Annotated[list[str] | None, FilterLookup("name__in")] # Works
type name_list = list[str] | None # Failes
name_list = list[str] | None # Works

Versions

Python version: 3.14
Django version: 6.0.4
Django-Ninja version: 1.6.2
Pydantic version: 2.13.3

Source: vitalik/django-ninja

View original on GitHub View discussion on GitHub