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

A JSON example of this model.

"asc"

The JSON Schema for this model.

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

The TypeSpec code for this model.

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

The Python code for this model.

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

    ASC = "asc"
    DESC = "desc"

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

A JSON example of this model.

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

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

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;
}

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],
    )

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

A JSON example of this model.

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

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

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;
}

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],
    )

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

A JSON example of this model.

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

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

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[];
}

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"}},
    )

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