Skip to content

# `schemas`

Here's the reference for all response models and types provided by the `schemas` module.

You can import them directly from `fastapi_toolsets.schemas`:

    from fastapi_toolsets.schemas import (
        PydanticBase,
        ResponseStatus,
        ApiError,
        BaseResponse,
        Response,
        ErrorResponse,
        OffsetPagination,
        CursorPagination,
        PaginationType,
        PaginatedResponse,
        OffsetPaginatedResponse,
        CursorPaginatedResponse,
    )

## `fastapi_toolsets.schemas.PydanticBase`

Bases: `BaseModel`

Base class for all Pydantic models with common configuration.

## `fastapi_toolsets.schemas.ResponseStatus`

Bases: `str`, `Enum`

Standard API response status.

## `fastapi_toolsets.schemas.ApiError`

Bases: `PydanticBase`

Structured API error definition.

Used to define standard error responses with consistent format.

Attributes:

Name | Type | Description
--- | --- | ---
`code` | `int` | HTTP status code
`msg` | `str` | Short error message
`desc` | `str` | Detailed error description
`err_code` | `str` | Application-specific error code (e.g., "AUTH-401")

## `fastapi_toolsets.schemas.BaseResponse`

Bases: `PydanticBase`

Base response structure for all API responses.

Attributes:

Name | Type | Description
--- | --- | ---
`status` | `ResponseStatus` | SUCCESS or FAIL
`message` | `str` | Human-readable message
`error_code` | `str | None` | Error code if status is FAIL, None otherwise

## `fastapi_toolsets.schemas.Response`

Bases: `BaseResponse`, `Generic[DataT]`

Generic API response with data payload.

Example

    Response[UserRead](data=user, message="User retrieved")

## `fastapi_toolsets.schemas.ErrorResponse`

Bases: `BaseResponse`

Error response with additional description field.

Used for error responses that need more context.

## `fastapi_toolsets.schemas.OffsetPagination`

Bases: `PydanticBase`

Pagination metadata for offset-based list responses.

Attributes:

Name | Type | Description
--- | --- | ---
`total_count` | `int | None` | Total number of items across all pages. `None` when `include_total=False`.
`items_per_page` | `int` | Number of items per page
`page` | `int` | Current page number (1-indexed)
`has_more` | `bool` | Whether there are more pages
`pages` | `int | None` | Total number of pages

### `pages` `property`

Total number of pages, or `None` when `total_count` is unknown.

## `fastapi_toolsets.schemas.CursorPagination`

Bases: `PydanticBase`

Pagination metadata for cursor-based list responses.

Attributes:

Name | Type | Description
--- | --- | ---
`next_cursor` | `str | None` | Encoded cursor for the next page, or None on the last page.
`prev_cursor` | `str | None` | Encoded cursor for the previous page, or None on the first page.
`items_per_page` | `int` | Number of items requested per page.
`has_more` | `bool` | Whether there is at least one more page after this one.

## `fastapi_toolsets.schemas.PaginationType`

Bases: `str`, `Enum`

Pagination strategy selector for :meth:`.AsyncCrud.paginate`.

## `fastapi_toolsets.schemas.PaginatedResponse`

Bases: `BaseResponse`, `Generic[DataT]`

Paginated API response for list endpoints.

Base class and return type for endpoints that support both pagination strategies. Use :class:`OffsetPaginatedResponse` or :class:`CursorPaginatedResponse` when the strategy is fixed.

When used as `PaginatedResponse[T]` in a return annotation, subscripting returns `Annotated[Union[CursorPaginatedResponse[T], OffsetPaginatedResponse[T]], Field(discriminator="pagination_type")]` so FastAPI emits a proper `oneOf` + discriminator in the OpenAPI schema.

## `fastapi_toolsets.schemas.OffsetPaginatedResponse`

Bases: `PaginatedResponse[DataT]`

Paginated response with typed offset-based pagination metadata.

The `pagination_type` field is always `"offset"` and acts as a discriminator, allowing frontend clients to narrow the union type returned by a unified `paginate()` endpoint.

## `fastapi_toolsets.schemas.CursorPaginatedResponse`

Bases: `PaginatedResponse[DataT]`

Paginated response with typed cursor-based pagination metadata.

The `pagination_type` field is always `"cursor"` and acts as a discriminator, allowing frontend clients to narrow the union type returned by a unified `paginate()` endpoint.