Sorting

SortOrder

The order or direction to sort results by.

Table

| Value | Description | | ----- | ---------------------------------------------- | | asc | Ascending order (e.g., low to high or A to Z) | | desc | Descending order (e.g., high to low or Z to A) |

Formats

Example

A JSON example of this model.

"asc"

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: SortOrder.yaml
type: string
enum:
  - asc
  - desc

TypeSpec

The TypeSpec code for this model.

@Versioning.added(CommonGrants.Versions.v0_1)
enum SortOrder {
  asc,
  desc,
}

Python

The Python code for this model.

class SortOrder(str, Enum):
    """Sort order enumeration."""

    ASC = "asc"
    DESC = "desc"

TypeScript

The TypeScript code for this model.

export const SortOrderEnum = z.enum(["asc", "desc"]);

Changelog

Version	Changes	Schema
0.1.0	Added SortOrder enum	SortOrder.yaml

SortQueryParams

Query parameters for sorting. These parameters should be used on GET routes that support sorting.

Table

| Parameter | Type | Description | | ------------ | ---------------------------------------- | ------------------------------------------------------------- | | sortBy | unknown | The field to sort by, should be an enum for individual routes | | customSortBy | string | An implementation-defined sort key | | sortOrder | SortOrder | The order to sort by |

Formats

Example

A JSON example of this model.

{
  "sortBy": "lastModifiedAt",
  "customSortBy": "customField",
  "sortOrder": "asc"
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: SortQueryParams.yaml
type: object
properties:
  sortBy:
    examples:
      - lastModifiedAt
    description: The field to sort by
  customSortBy:
    type: string
    examples:
      - customField
    description: Implementation-defined sort key
  sortOrder:
    $ref: SortOrder.yaml
    examples:
      - asc
    description: The order to sort by
required:
  - sortBy
unevaluatedProperties:
  not: {}
description: Query parameters for sorting

TypeSpec

The TypeSpec code for this model.

/** Query parameters for sorting */
@Versioning.added(CommonGrants.Versions.v0_1)
model SortQueryParams {
  /** The field to sort by */
  @query
  @example("lastModifiedAt")
  sortBy: unknown;

  /** Implementation-defined sort key */
  @query
  @example("customField")
  customSortBy?: string;

  /** The order to sort by */
  @query
  @example(SortOrder.asc)
  sortOrder?: SortOrder;
}

Python

The Python code for this model.

class SortQueryParams(SortBase):
    """Query parameters for sorting."""

    sort_order: Optional[SortOrder] = Field(
        default=None,
        alias="sortOrder",
        description="The order to sort by",
        examples=[SortOrder.ASC],
    )

TypeScript

The TypeScript code for this model.

export const SortQueryParamsSchema = z.object({
  /** The field to sort by */
  sortBy: z.unknown(),

  /** Implementation-defined sort key */
  customSortBy: z.string().nullish(),

  /** The order to sort by */
  sortOrder: SortOrderEnum.nullish(),
});

Changelog

Version	Changes	Schema
0.1.0	Added SortQueryParams model	SortQueryParams.yaml

SortBodyParams

Body parameters for sorting. These parameters should be used on POST and PUT routes that support sorting.

Table

| Parameter | Type | Description | | ------------ | ---------------------------------------- | ------------------------------------------------------------- | | sortBy | unknown | The field to sort by, should be an enum for individual routes | | customSortBy | string | An implementation-defined sort key | | sortOrder | SortOrder | The order to sort by |

Formats

Example

A JSON example of this model.

{
  "sortBy": "lastModifiedAt",
  "customSortBy": "customField",
  "sortOrder": "asc"
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: SortBodyParams.yaml
type: object
properties:
  sortBy:
    examples:
      - lastModifiedAt
    description: The field to sort by
  customSortBy:
    type: string
    examples:
      - customField
    description: Implementation-defined sort key
  sortOrder:
    $ref: SortOrder.yaml
    examples:
      - asc
    description: The order to sort by
required:
  - sortBy
description: Sorting parameters included in the request body

TypeSpec

The TypeSpec code for this model.

/** Sorting parameters included in the request body */
@Versioning.added(CommonGrants.Versions.v0_1)
model SortBodyParams {
  /** The field to sort by */
  @example("lastModifiedAt")
  sortBy: unknown;

  /** Implementation-defined sort key */
  @example("customField")
  customSortBy?: string;

  /** The order to sort by */
  @example(SortOrder.asc)
  sortOrder?: SortOrder;
}

Python

The Python code for this model.

class SortBodyParams(SortBase):
    """Sorting parameters included in the request body."""

    sort_order: Optional[SortOrder] = Field(
        default=None,
        alias="sortOrder",
        description="The order to sort by",
        examples=[SortOrder.ASC],
    )

TypeScript

The TypeScript code for this model.

export const SortBodyParamsSchema = z.object({
  /** The field to sort by */
  sortBy: z.unknown(),

  /** Implementation-defined sort key */
  customSortBy: z.string().nullish(),

  /** The order to sort by */
  sortOrder: SortOrderEnum.nullish(),
});

Changelog

Version	Changes	Schema
0.1.0	Added SortBodyParams model	SortBodyParams.yaml

SortedResultsInfo

Information about the sort order of the items returned. This model should be included in responses that support sorting.

Table

| Parameter | Type | Description | | ------------ | ------------------------------------------------------------------------------- | --------------------------------------- | | sortBy | string | The field to sort by | | customSortBy | string | An implementation-defined sort key | | sortOrder | SortOrder | The order to sort by | | errors | Array<string> | The errors that occurred during sorting |

Formats

Example

A JSON example of this model.

{
  "sortBy": "lastModifiedAt",
  "customSortBy": "customField",
  "sortOrder": "asc",
  "errors": [
    "string"
  ]
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: SortedResultsInfo.yaml
type: object
properties:
  sortBy:
    type: string
    examples:
      - lastModifiedAt
    description: The field results are sorted by, or "custom" if an implementation-defined sort key is used
  customSortBy:
    type: string
    examples:
      - customField
    description: Implementation-defined sort key used to sort the results, if applicable
  sortOrder:
    $ref: SortOrder.yaml
    examples:
      - asc
    description: The order in which the results are sorted, e.g. ascending or descending
  errors:
    type: array
    items:
      type: string
    description: Non-fatal errors that occurred during sorting
required:
  - sortBy
  - sortOrder
unevaluatedProperties:
  not: {}
description: Information about the sort order of the items returned

TypeSpec

The TypeSpec code for this model.

/** Information about the sort order of the items returned */
@Versioning.added(CommonGrants.Versions.v0_1)
model SortedResultsInfo {
  /** The field results are sorted by, or "custom" if an implementation-defined sort key is used */
  @example("lastModifiedAt")
  sortBy: string;

  /** Implementation-defined sort key used to sort the results, if applicable */
  @example("customField")
  customSortBy?: string;

  /** The order in which the results are sorted, e.g. ascending or descending */
  @example(SortOrder.asc)
  sortOrder: SortOrder;

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

Python

The Python code for this model.

class SortedResultsInfo(SortBase):
    """Sorting information for search results."""

    sort_order: str = Field(
        ...,
        alias="sortOrder",
        description="The order in which the results are sorted",
    )
    errors: Optional[list[str]] = Field(
        default_factory=lambda: [],
        description="Non-fatal errors that occurred during sorting",
        json_schema_extra={"items": {"type": "string"}},
    )

TypeScript

The TypeScript code for this model.

export const SortedResultsInfoSchema = z.object({
  /** The field results are sorted by, or "custom" if an implementation-defined sort key is used */
  sortBy: z.string(),

  /** Implementation-defined sort key used to sort the results, if applicable */
  customSortBy: z.string().nullish(),

  /** The order in which the results are sorted, e.g. ascending or descending */
  sortOrder: SortOrderEnum,

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

Changelog

Version	Changes	Schema
0.1.0	Added SortedResultsInfo model	SortedResultsInfo.yaml