Filtered

Filtered

A 200 response with a paginated list of filtered items.

Table

Parameter	Type	Description
status	integer	The HTTP status code
message	string	The message to return
items	Array	Items from the current page
paginationInfo	PaginatedResultsInfo	Details about the pagination
sortInfo	SortedResultsInfo	The sort order of the items
filterInfo	object	The filters applied to the response items

Formats

Example

A JSON example of this model.

{
  "status": 200,
  "message": "Success",
  "items": [
    {
      "id": "123",
      "name": "Test 1"
    },
    {
      "id": "124",
      "name": "Test 2"
    }
  ],
  "paginationInfo": {
    "page": 1,
    "pageSize": 10,
    "totalItems": 25,
    "totalPages": 3
  },
  "sortInfo": {
    "field": "name",
    "direction": "asc"
  },
  "filterInfo": {
    "filters": {
      "lastModifiedAt": {
        "operator": "gte",
        "value": "2024-01-01T00:00:00Z"
      },
      "status": {
        "operator": "in",
        "value": [
          "active",
          "inactive"
        ]
      }
    }
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: Filtered.yaml
type: object
properties:
  items:
    type: array
    items: {}
    description: Items from the current page
  paginationInfo:
    $ref: PaginatedResultsInfo.yaml
    description: Details about the paginated results
  sortInfo:
    $ref: SortedResultsInfo.yaml
    description: The sort order of the items
  filterInfo:
    type: object
    properties:
      filters: {}
      errors:
        type: array
        items:
          type: string
        description: Non-fatal errors that occurred during filtering
    required:
      - filters
    unevaluatedProperties:
      not: {}
    description: The filters applied to the response items
required:
  - items
  - paginationInfo
  - sortInfo
  - filterInfo
allOf:
  - $ref: Success.yaml
unevaluatedProperties:
  not: {}
description: A paginated list of items with a filter

TypeSpec

The TypeSpec code for this model.

@Versioning.added(CommonGrants.Versions.v0_1)
model FilteredBase<ItemsT, FilterT> {
  ...SortedBase<ItemsT>;

  /** The filters applied to the response items */
  filterInfo: {
    filters: FilterT;

    /** Non-fatal errors that occurred during filtering */
    errors?: string[];
  };
}

/** A paginated list of items of an unspecified shape with a filter
 *
 * Routes use the typed `FilteredT<ItemsT, FilterT>` variant.
 */
@doc("A paginated list of items with a filter")
@Versioning.added(CommonGrants.Versions.v0_1)
model Filtered extends Success {
  ...FilteredBase<unknown, unknown>;
}

Python

The Python code for this model.

class FilterInfo(CommonGrantsBaseModel, Generic[FilterT]):
    """Filter information for search results."""

    filters: FilterT = Field(
        ..., description="The filters applied to the response items"
    )
    errors: Optional[list[str]] = Field(
        default_factory=lambda: [],
        description="Non-fatal errors that occurred during filtering",
    )


class Filtered(Sorted[ItemsT], Generic[ItemsT, FilterT]):
    """A paginated list of items with a filter."""

    filter_info: FilterInfo[FilterT] = Field(
        ...,
        description="The filters applied to the response items",
        alias="filterInfo",
    )

    model_config = {"populate_by_name": True}

TypeScript

The TypeScript code for this model.

export const FilteredSchema = <ItemsT extends z.ZodTypeAny, FilterT extends z.ZodTypeAny>(
  itemsSchema: ItemsT,
  filterSchema: FilterT
) =>
  SortedSchema(itemsSchema).extend({
    /** The filters applied to the response items */
    filterInfo: z
      .object({
        filters: filterSchema,

        /** Non-fatal errors that occurred during filtering */
        errors: z.array(z.string()).nullish(),
      })
      .strict(),
  });

Usage

Use the FilteredT<ItemsT, FilterT> template to define a 200 response with a paginated list of filtered, typed items within an API operation:

import "@common-grants/core";
import "@typespec/http";

using TypeSpec.Http;
using CommonGrants.Pagination;
using CommonGrants.Responses;

model TestModel {
  id: string;
  name: string;
}

model TestFilter extends Record<Filters.DefaultFilter> {
  lastModifiedAt: Filters.DateComparisonFilter;
}

@summary("Search test models")
@doc("Get a paginated list of test models matching a filter")
@post
op searchTest(...PaginatedBodyParams): FilteredT<TestModel, TestFilter>;

Changelog

Version	Changes	Schema
0.1.0	Added Filtered model	Filtered.yaml