fix: wire-mode filter normalization (#439)

Corrects an issue where the frontend generates camel case schemas and there is a mismatch between allowed columns and configured filter dependency settings.

Author: cofin

docs/changelog.rst

@@ -10,7 +10,41 @@ SQLSpec Changelog
 Recent Updates
 ==============
 
-schema_dump wire_format Opt-Out (Unreleased)
+v0.46.2 - Framework Filter ``orderBy`` Aliases (Unreleased)
+-----------------------------------------------------------
+
+**Fixed:**
+
+* Litestar ``create_filter_dependencies()`` and FastAPI ``provide_filters()``
+  now accept camel-case API-facing sort aliases for configured ``orderBy``
+  fields by default. Endpoints can accept values such as
+  ``orderBy=uploadedCollections`` while producing an ``OrderByFilter`` for the
+  SQL-facing field ``uploaded_collections``. Raw configured values remain
+  accepted for compatibility, explicit aliases can still be added with
+  ``sort_field_aliases``, and ``sort_field_camelize=False`` restores
+  snake_case-only validation. (`#438
+  <https://github.com/litestar-org/sqlspec/issues/438>`_)
+
+**Safety:**
+
+* Alias normalization is closed over the configured ``sort_field`` allowlist.
+  Unknown aliases and aliases targeting fields outside ``sort_field`` are
+  rejected before SQL construction, preserving the existing identifier
+  allowlist.
+
+v0.46.1 - Litestar Filter Provider Binding Fix
+----------------------------------------------
+
+**Fixed:**
+
+* Litestar generated filter providers now use unique dependency parameter names
+  for sibling ``IN``, ``NOT IN``, null, not-null, and range filters. This stops
+  sibling providers in the same filter family from cross-binding values while
+  preserving the existing query parameter aliases. (`#435
+  <https://github.com/litestar-org/sqlspec/issues/435>`_, `#436
+  <https://github.com/litestar-org/sqlspec/pull/436>`_)
+
+v0.46.0 - ``schema_dump`` Wire-Format Opt-Out
 ---------------------------------------------
 
 **Added:**
@@ -27,8 +61,8 @@ schema_dump wire_format Opt-Out (Unreleased)
 * The internal serializer cache key now includes ``wire_format`` so that
   ``True`` and ``False`` calls for the same Struct type cannot collide.
 
-Schema Wire Correctness (Unreleased)
--------------------------------------
+v0.44.0 - Schema Wire Correctness
+---------------------------------
 
 **Fixed:**
 

docs/examples/patterns/filter_dependencies.py

@@ -11,7 +11,9 @@ def show_filter_dependencies() -> None:
     user_filters: FilterConfig = {
         "id_filter": str,  # Filter by user IDs
         "id_field": "id",  # Column name for ID filter
-        "sort_field": ["created_at", "name"],  # Allowed sort columns
+        "sort_field": ["created_at", "uploaded_collections", "name"],  # Allowed sort columns
+        # orderBy accepts camel aliases like uploadedCollections by default
+        "sort_field_aliases": {"lastUpload": "uploaded_collections"},  # Optional non-mechanical aliases
         "sort_order": "desc",  # Default sort direction
         "pagination_type": "limit_offset",  # Enable pagination
         "pagination_size": 20,  # Default page size

docs/recipes/service_layer.rst

@@ -371,7 +371,7 @@ forwarded through the service to the driver:
        dependencies = create_filter_dependencies({
            "pagination_type": "limit_offset",
            "pagination_size": 20,
-           "sort_field": ["created_at", "name"],
+           "sort_field": ["created_at", "uploaded_collections", "name"],
            "sort_order": "desc",
            "search": "name,email",
        })
@@ -384,6 +384,13 @@ forwarded through the service to the driver:
        ) -> OffsetPagination[User]:
            return await users_service.list_with_count(*filters)
 
+``sort_field`` remains the SQL-facing allowlist. Clients can request
+``?orderBy=uploadedCollections`` by default while the service receives an
+``OrderByFilter`` for ``uploaded_collections``. Existing snake_case values, such
+as ``?orderBy=uploaded_collections``, remain valid for compatibility. Set
+``sort_field_camelize=False`` when an endpoint must accept only raw configured
+``orderBy`` values.
+
 .. seealso::
 
    - :doc:`/usage/drivers_and_querying` for the driver methods used here

docs/reference/extensions/fastapi.rst

@@ -15,6 +15,13 @@ Plugin
 Dependency Helpers
 ==================
 
+``provide_filters()`` supports the same ``orderBy`` alias contract as the
+Litestar provider. Camel-case query values are accepted by default for
+configured ``sort_field`` values. Use ``sort_field_aliases`` for explicit API
+names, or set ``sort_field_camelize=False`` to accept only raw configured
+values. Alias values normalize to fields from ``sort_field`` before
+``OrderByFilter`` is created, so the SQL-facing sort allowlist remains strict.
+
 .. autofunction:: sqlspec.extensions.fastapi.provide_filters
 
 .. autoclass:: sqlspec.extensions.fastapi.DependencyDefaults

docs/reference/extensions/litestar.rst

@@ -36,6 +36,13 @@ Store
 Providers
 =========
 
+``create_filter_dependencies()`` accepts camel-case aliases for configured
+``orderBy`` fields by default. Use ``sort_field_aliases`` to map explicit API
+names to configured SQL-facing fields, or set ``sort_field_camelize=False`` when
+an endpoint must accept only raw configured values. Alias values are normalized
+before ``OrderByFilter`` is created, and unknown aliases cannot bypass the
+``sort_field`` allowlist.
+
 .. autoclass:: sqlspec.extensions.litestar.providers.DependencyDefaults
    :members:
    :show-inheritance:

docs/usage/filtering.rst

@@ -2,7 +2,8 @@ Filtering & Pagination
 ======================
 
 SQLSpec provides filter types and pagination helpers that work with any driver.
-The Litestar extension includes auto-generated filter dependencies for REST APIs.
+The Litestar and FastAPI extensions include auto-generated filter dependencies
+for REST APIs.
 
 Pagination with SQL Objects
 ---------------------------
@@ -68,13 +69,14 @@ Search Patterns
 that returns the percent-wrapped search value (e.g. ``%alice%``). This is useful
 when you need to use the pattern construction logic outside of the filter system.
 
-Litestar Filter Dependencies
-
+Framework Filter Dependencies
 -----------------------------
 
 When using the Litestar extension, ``create_filter_dependencies()`` auto-generates
-Litestar dependency providers from a declarative configuration. These providers
-parse query parameters from incoming requests and produce filter objects.
+Litestar dependency providers from a declarative configuration. FastAPI provides
+the same filter contract through ``SQLSpecPlugin.provide_filters()`` for use with
+``Depends()``. These providers parse query parameters from incoming requests and
+produce filter objects.
 
 .. literalinclude:: /examples/patterns/filter_dependencies.py
    :language: python
@@ -95,7 +97,7 @@ Using filters in a Litestar handler:
     user_filter_deps = create_filter_dependencies({
         "pagination_type": "limit_offset",
         "pagination_size": 20,
-        "sort_field": ["created_at", "name"],
+        "sort_field": ["created_at", "uploaded_collections", "name"],
         "sort_order": "desc",
         "search": "name,email",
     })
@@ -110,7 +112,46 @@ Using filters in a Litestar handler:
         return {"data": data, "total": total}
 
 The generated dependencies automatically handle query parameters for configured fields like
-``?currentPage=2&pageSize=10&searchString=alice&orderBy=name&sortOrder=asc``.
+``?currentPage=2&pageSize=10&searchString=alice&orderBy=uploadedCollections&sortOrder=asc``.
+Camelized ``orderBy`` values are accepted by default for every configured
+``sort_field`` value, so ``orderBy=uploadedCollections`` is normalized to the
+SQL-facing field ``uploaded_collections`` before the ``OrderByFilter`` is
+created. Raw configured values such as ``orderBy=uploaded_collections`` also
+remain accepted for compatibility.
+
+Sort aliases are closed over the configured ``sort_field`` allowlist. Use
+``sort_field_aliases`` when the public API name is not a mechanical camel-case
+conversion, or set ``sort_field_camelize=False`` to require raw configured
+``orderBy`` values only:
+
+.. code-block:: python
+
+    user_filter_deps = create_filter_dependencies({
+        "sort_field": ["created_at", "uploaded_collections"],
+        "sort_field_aliases": {"lastUpload": "uploaded_collections"},
+    })
+
+    snake_case_only_filter_deps = create_filter_dependencies({
+        "sort_field": ["created_at", "uploaded_collections"],
+        "sort_field_camelize": False,
+    })
+
+``orderBy=lastUpload`` is accepted, but aliases that target fields outside
+``sort_field`` are rejected when the provider is created. Unknown ``orderBy``
+values still fail validation before reaching SQL construction.
+
+For FastAPI, use the same configuration with ``Depends()``:
+
+.. code-block:: python
+
+    filters = Depends(
+        db_ext.provide_filters({
+            "sort_field": ["created_at", "uploaded_collections"],
+        })
+    )
+
+SQLSpec does not ship generated filter providers for Flask, Starlette, or Sanic;
+their integrations do not have a runtime ``orderBy`` alias surface.
 
 Service Layer
 -------------

pyproject.toml

@@ -24,7 +24,7 @@ maintainers = [{ name = "Litestar Developers", email = "hello@litestar.dev" }]
 name = "sqlspec"
 readme = "README.md"
 requires-python = ">=3.10, <4.0"
-version = "0.46.1"
+version = "0.46.2"
 
 [project.urls]
 Discord = "https://discord.gg/litestar"
@@ -264,7 +264,7 @@ opt_level = "3"   # Maximum optimization (0-3)
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "0.46.1"
+current_version = "0.46.2"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

sqlspec/extensions/_filter_aliases.py

@@ -0,0 +1,112 @@
+"""Shared filter alias helpers for framework extensions."""
+
+from collections.abc import Mapping
+from typing import NamedTuple
+
+from sqlspec.utils.text import camelize
+
+__all__ = ("SortField", "SortFieldResolution", "resolve_sort_field_aliases")
+
+SortField = str | set[str] | list[str]
+
+
+class SortFieldResolution(NamedTuple):
+    """Resolved sort-field alias metadata.
+
+    Args:
+        default_field: Internal SQL-facing field used when no query value is supplied.
+        default_query_value: API-facing default value exposed on the query parameter.
+        allowed_fields: Internal SQL-facing allowlist.
+        inbound_aliases: API-facing query values mapped to internal field names.
+        field_display_names: Internal field names mapped to their preferred API-facing display names.
+        allowed_display_names: Display names ordered to match the configured sort fields.
+    """
+
+    default_field: str
+    default_query_value: str
+    allowed_fields: frozenset[str]
+    inbound_aliases: dict[str, str]
+    field_display_names: dict[str, str]
+    allowed_display_names: tuple[str, ...]
+
+    def normalize(self, value: str | None) -> str | None:
+        """Normalize a query value to an internal field name.
+
+        Args:
+            value: API-facing query value, or ``None`` to request the default field.
+
+        Returns:
+            The internal field name if the value is configured, otherwise ``None``.
+        """
+        if value is None:
+            return self.default_field
+        return self.inbound_aliases.get(value)
+
+
+def resolve_sort_field_aliases(
+    sort_field: SortField, sort_field_aliases: Mapping[str, str] | None = None, sort_field_camelize: bool = True
+) -> SortFieldResolution:
+    """Resolve sort-field aliases to a closed allowlist map.
+
+    Args:
+        sort_field: Configured SQL-facing sort field or fields.
+        sort_field_aliases: Optional API-facing alias to SQL-facing field mapping.
+        sort_field_camelize: Whether to generate camel-case aliases for configured fields. Defaults to ``True``.
+
+    Returns:
+        Precomputed alias metadata for framework filter providers.
+
+    Raises:
+        ValueError: If an alias targets an unknown field or collides with a different field.
+    """
+    fields = _coerce_fields(sort_field)
+    allowed_fields = frozenset(fields)
+    inbound_aliases: dict[str, str] = {}
+    field_display_names = {field: field for field in fields}
+
+    for field in fields:
+        _add_alias(inbound_aliases, alias=field, field=field)
+
+    if sort_field_camelize:
+        for field in fields:
+            alias = camelize(field)
+            _add_alias(inbound_aliases, alias=alias, field=field)
+            field_display_names[field] = alias
+
+    if sort_field_aliases:
+        for alias, field in sort_field_aliases.items():
+            if field not in allowed_fields:
+                msg = f"sort field alias '{alias}' targets unknown sort field '{field}'"
+                raise ValueError(msg)
+            _add_alias(inbound_aliases, alias=alias, field=field)
+            field_display_names[field] = alias
+
+    allowed_display_names = tuple(field_display_names[field] for field in fields)
+    return SortFieldResolution(
+        default_field=fields[0],
+        default_query_value=field_display_names[fields[0]],
+        allowed_fields=allowed_fields,
+        inbound_aliases=inbound_aliases,
+        field_display_names=field_display_names,
+        allowed_display_names=allowed_display_names,
+    )
+
+
+def _coerce_fields(sort_field: SortField) -> tuple[str, ...]:
+    if isinstance(sort_field, str):
+        return (sort_field,)
+    fields = tuple(sorted(sort_field)) if isinstance(sort_field, set) else tuple(sort_field)
+    if not fields:
+        msg = "sort_field must include at least one field"
+        raise ValueError(msg)
+    return fields
+
+
+def _add_alias(inbound_aliases: dict[str, str], *, alias: str, field: str) -> None:
+    existing_field = inbound_aliases.get(alias)
+    if existing_field is None or existing_field == field:
+        inbound_aliases[alias] = field
+        return
+
+    msg = f"ambiguous sort field alias '{alias}' maps to both '{existing_field}' and '{field}'"
+    raise ValueError(msg)

sqlspec/extensions/fastapi/extension.py

@@ -374,7 +374,7 @@ async def list_users(
                         "search": "name,email",
                         "search_ignore_case": True,
                         "pagination_type": "limit_offset",
-                        "sort_field": "created_at",
+                        "sort_field": ["created_at", "uploaded_collections"],
                     })
                 ),
             ):