Success responses

Standard 2xx response envelopes.

Success

Property	Type	Required	Description
`status`	`number`	Yes
`message`	`string`	Yes

{
  "status": 200,
  "message": "Success"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: Success.yaml
type: object
properties:
  status:
    type: number
    examples:
      - 200
  message:
    type: string
    examples:
      - Success
required:
  - status
  - message

@Versioning.added(Versions.v0_1)
model Success {
  @example(200)
  status: numeric;

  @example("Success")
  message: string;
}

Ok

A 200 response with data

Property	Type	Required	Description
`status`	`number`	Yes
`data`	`unknown`	Yes	Response data.
`message`	`string`	Yes

{
  "status": 200,
  "data": null,
  "message": "Success"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: Ok.yaml
type: object
properties:
  status:
    type: number
    examples:
      - 200
  data:
    description: Response data.
  message:
    type: string
    examples:
      - Success
required:
  - status
  - data
  - message
description: A 200 response with data

/** A 200 response with data of an unspecified shape.
 *
 * Use this when you need a concrete (non-generic) schema in the emitted
 * JSON Schema / OpenAPI output. For a typed variant, see `OkT<T>`.
 */
@doc("A 200 response with data")
@Versioning.added(Versions.v0_1)
model Ok extends Success {
  // Concrete (documentation) responses pin the body `status` as a literal. The
  // HTTP status code is carried by the templated `*T` variants via
  // `...Http.*Response`, which are the models actually used by routes.
  status: 200;

  /** Response data. */
  data: unknown;
}

Created

A 201 response with data of an unspecified shape. For a typed variant, see `CreatedT`.

Property	Type	Required	Description
`status`	`number`	Yes
`data`	`unknown`	Yes	Response data.
`message`	`string`	Yes

{
  "status": 201,
  "data": null,
  "message": "Success"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: Created.yaml
type: object
properties:
  status:
    type: number
    examples:
      - 200
  data:
    description: Response data.
  message:
    type: string
    examples:
      - Success
required:
  - status
  - data
  - message
description: |-
  A 201 response with data of an unspecified shape.

  For a typed variant, see `CreatedT<T>`.

/** A 201 response with data of an unspecified shape.
 *
 * For a typed variant, see `CreatedT<T>`.
 */
@Versioning.added(Versions.v0_1)
model Created extends Success {
  @example(201)
  status: 201;

  /** Response data. */
  data: unknown;
}

Paginated

A 200 response with a paginated list of items

Property	Type	Required	Description
`status`	`number`	Yes
`items`	`unknown`[]	Yes	Items from the current page.
`paginationInfo`	`PaginatedResultsInfo`	Yes	Details about the paginated results.
`message`	`string`	Yes

{
  "status": 200,
  "items": [],
  "paginationInfo": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 100,
    "totalPages": 5
  },
  "message": "Success"
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: Paginated.yaml
type: object
properties:
  status:
    type: number
    examples:
      - 200
  items:
    type: array
    items: {}
    description: Items from the current page.
  paginationInfo:
    $ref: PaginatedResultsInfo.yaml
    description: Details about the paginated results.
  message:
    type: string
    examples:
      - Success
required:
  - status
  - items
  - paginationInfo
  - message
description: A 200 response with a paginated list of items

/** A 200 response with a paginated list of items of an unspecified shape.
 *
 * For a typed variant, see `PaginatedT<T>`.
 */
@doc("A 200 response with a paginated list of items")
@Versioning.added(Versions.v0_1)
model Paginated is PaginatedBase<unknown>;

/** Template for a 200 response with a paginated list of typed items.
 *
 * @template T The schema for the value of the `"items"` property in this response.
 */
@doc("A 200 response with a paginated list of typed items")
@Versioning.added(Versions.v0_1)
model PaginatedT<T> extends PaginatedBase<T> {
  ...Http.OkResponse;
}

Filtered

A paginated list of items with a filter

Property	Type	Required	Description
`status`	`number`	Yes
`items`	`unknown`[]	Yes	Items from the current page.
`paginationInfo`	`PaginatedResultsInfo`	Yes	Details about the paginated results.
`message`	`string`	Yes
`sortInfo`	`SortedResultsInfo`	Yes	The sort order of the items.
`filterInfo`	`object`	Yes	The filters applied to the response items.

{
  "status": 200,
  "items": [],
  "paginationInfo": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 100,
    "totalPages": 5
  },
  "message": "Success",
  "sortInfo": {
    "sortBy": "lastModifiedAt",
    "customSortBy": "customField",
    "sortOrder": "asc",
    "errors": [
      "string"
    ]
  },
  "filterInfo": {
    "filters": null,
    "errors": [
      "string"
    ]
  }
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: Filtered.yaml
type: object
properties:
  status:
    type: number
    const: 200
  items:
    type: array
    items: {}
    description: Items from the current page.
  paginationInfo:
    $ref: PaginatedResultsInfo.yaml
    description: Details about the paginated results.
  message:
    type: string
    examples:
      - Success
  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
    description: The filters applied to the response items.
required:
  - status
  - items
  - paginationInfo
  - message
  - sortInfo
  - filterInfo
description: A paginated list of items with a filter

/** A paginated list of items with a filter applied. */
@doc("A paginated list of items with a filter")
@Versioning.added(Versions.v0_1)
model Filtered is FilteredBase<unknown, unknown>;

/** A paginated list of typed items with a typed filter applied.
 *
 * @template ItemsT The schema for the value of the `"items"` property in this response.
 * @template FilterT The schema for the value of the `"filter"` property in this response.
 */
@doc("A paginated list of typed items with a typed filter")
@Versioning.added(Versions.v0_1)
model FilteredT<ItemsT, FilterT> extends FilteredBase<ItemsT, FilterT> {
  ...Http.OkResponse;
}

Sorted

A paginated list of items with a sort order

Property	Type	Required	Description
`status`	`number`	Yes
`items`	`unknown`[]	Yes	Items from the current page.
`paginationInfo`	`PaginatedResultsInfo`	Yes	Details about the paginated results.
`message`	`string`	Yes
`sortInfo`	`SortedResultsInfo`	Yes	The sort order of the items.

{
  "status": 200,
  "items": [],
  "paginationInfo": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 100,
    "totalPages": 5
  },
  "message": "Success",
  "sortInfo": {
    "sortBy": "lastModifiedAt",
    "customSortBy": "customField",
    "sortOrder": "asc",
    "errors": [
      "string"
    ]
  }
}

$schema: https://json-schema.org/draft/2020-12/schema
$id: Sorted.yaml
type: object
properties:
  status:
    type: number
    const: 200
  items:
    type: array
    items: {}
    description: Items from the current page.
  paginationInfo:
    $ref: PaginatedResultsInfo.yaml
    description: Details about the paginated results.
  message:
    type: string
    examples:
      - Success
  sortInfo:
    $ref: SortedResultsInfo.yaml
    description: The sort order of the items.
required:
  - status
  - items
  - paginationInfo
  - message
  - sortInfo
description: A paginated list of items with a sort order

/** A paginated list of items with a sort order. */
@doc("A paginated list of items with a sort order")
@Versioning.added(Versions.v0_1)
model Sorted is SortedBase<unknown>;

/** A paginated list of typed items with a sort order.
 *
 * @template T The schema for the value of the `"items"` property in this response.
 */
@doc("A paginated list of typed items with a sort order")
@Versioning.added(Versions.v0_1)
model SortedT<T> extends SortedBase<T> {
  ...Http.OkResponse;
}