Sorting

Sorting is layered on top of pagination. A request specifies the field to sort by and a direction; the response carries the resolved sort key back so clients can verify or display it.

SortQueryParams

Query parameters for sorting.

Property	Type	Required	Description
sortBy	unknown	Yes	The field to sort by.
customSortBy	string	No	Implementation-defined sort key.
sortOrder	SortOrder	No	The order to sort by.

Example

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

JSON Schema

$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
description: Query parameters for sorting.

TypeSpec

/** Query parameters for sorting. */
@Versioning.added(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;
}

SortBodyParams

Sorting parameters included in the request body.

Property	Type	Required	Description
sortBy	unknown	Yes	The field to sort by.
customSortBy	string	No	Implementation-defined sort key.
sortOrder	SortOrder	No	The order to sort by.

Example

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

JSON Schema

$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

/** Sorting parameters included in the request body. */
@Versioning.added(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;
}

SortedResultsInfo

Information about the sort order of the items returned.

Property	Type	Required	Description
sortBy	string	Yes	The field results are sorted by, or "custom" if an implementation-defined sort key is used.
customSortBy	string	No	Implementation-defined sort key used to sort the results, if applicable.
sortOrder	SortOrder	Yes	The order in which the results are sorted (ascending or descending).
errors	string[]	No	Non-fatal errors that occurred during sorting.

Example

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

JSON Schema

$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 (ascending or descending).
  errors:
    type: array
    items:
      type: string
    description: Non-fatal errors that occurred during sorting.
required:
  - sortBy
  - sortOrder
description: Information about the sort order of the items returned.

TypeSpec

/** Information about the sort order of the items returned. */
@Versioning.added(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 (ascending or descending). */
  @example(SortOrder.asc)
  sortOrder: SortOrder;

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

SortOrder

Direction in which to sort a list of items.

Value	Description
asc	Ascending order (A→Z, 0→9, oldest→newest).
desc	Descending order (Z→A, 9→0, newest→oldest).

Example

"asc"

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: SortOrder.yaml
type: string
enum:
  - asc
  - desc
description: |-
  Direction in which to sort a list of items.

  - `asc`: Ascending order (A→Z, 0→9, oldest→newest).
  - `desc`: Descending order (Z→A, 9→0, newest→oldest).

TypeSpec

/** Direction in which to sort a list of items.
 *
 * - `asc`: Ascending order (A→Z, 0→9, oldest→newest).
 * - `desc`: Descending order (Z→A, 9→0, newest→oldest).
 */
@Versioning.added(Versions.v0_1)
enum SortOrder {
  /** Ascending order (A→Z, 0→9, oldest→newest). */
  asc,

  /** Descending order (Z→A, 9→0, newest→oldest). */
  desc,
}