Array Operators

sort

The sort operator arranges the items of the given array and returns a sorted version of that array. It never modifies the original input. You can use it to sort simple arrays, such as numbers, strings, and dates, or, arrays of objects using a specific field within each object. When sorting objects, you can also reference nested fields through dot notation.

This operator is useful when you need predictable ordering in mock responses, dynamic transformations, computed lists, or derived payloads that depend on user input or upstream data.

Syntax:

{{sort list-of-items "sort-by-key" "order"}}

Parameters

• list-of-items – Array to sort; JSON array strings are parsed automatically.
• sort-by-key (optional for primitives, required for objects) – Field to sort by; dot-notation allowed (user.profile.age).
• order (optional) – asc (default) or desc.

Behavior Guidelines

• Works with primitives (numbers, strings, dates) and objects.
• Sorting is case-sensitive for strings, numeric for numbers, and date-aware for date strings.
• When the list is made of objects, sorting based on deep/nested fields supported through dot notation.
• null / undefined elements inside arrays always move to the end.
• If input is not an array or parsable JSON array → value is returned unchanged.
• If the given list is null → returns null.
• Original array is never modified.

Examples

Use Case	Example	Output
Sort numbers ascending	{{sort (body "nums")}}	Request the request payload nums and sorts in ascending order.
Sort numbers descending	{{sort (body "nums") "desc"}}	Request the request payload nums and sorts in dascending order.
Sort objects by field	{{sort (body "cartItems") "price"}}	Reads shopping cart items from the request payload, and sorts them by price in ascending order.
Sort by nested field	{{sort (body "users") "name.firstName"}}	List of users are sorted alphabetical by their first name.
Sort stateful list	{{sort (list "get" "scores") "points" "desc"}}	Reads a stateful list (stored in Beeceptor), and returns a leaderboard sorted high→low scores.
Chain operations with reverse	{{reverse (sort (body "cartItems") "price")}}	First sort items and then reverse the list.
Chain operations with array	{{sort (array 'lion' 'zebra' 'aligator' 'elephant')}}	Sort an on-demand string array.

Reverse

The reverse operator flips the order of items in an array and returns a new reversed array. It does not change the original array. This operator is useful for generating alternate views of existing lists or preparing descending sequences.

Syntax

{{reverse list-of-items}}

Parameters

• list-of-items – The array to reverse. Can come from template context, request bodies, or state storage.

Behavior Guidelines

• Reverses any array regardless of mixed data types.
• Produces a new reversed array; original input is untouched.
• Non-array or non-parsable input → returned as-is.
• null or undefined → returns null.

oneOf (random pick)

The oneOf operator selects a random item from a provided list of values. You can supply any number of values, and this operator will pick one randomly. If no values are provided, it returns an empty string.

In the example below, the operator picks a random status from a list of possible application statuses.

Template definition:

{
  "status" : "{{oneOf  'draft' 'in-progress' 'approved' 'rejected'  'cancelled'}}"
}

Generated response:

{
  "status": "cancelled"
}

Demo:

someOf (random pick)

The someOf operator selects a random subset of items from a provided list of values. You can specify the number of items to pick from the list.

Syntax:

{{someOf array_expression min_items max_items stringify}}

Parameter	Required	Default	Description
array_expression	Yes	-	An array subexpression of values to pick from
min_items	No	0	Minimum number of items to pick
max_items	No	array_expression.length	Maximum number of items to pick
stringify	No	false	If true, the output will be a valid JSON array, use {{{}}} to escape

Example template definition:

{
  "owns-list": {{{someOf (array 'car' 'house' 'boat' 'bike' 'land') 1 2 true}}},
  "owns-string": "{{someOf (array 'car' 'house' 'boat' 'bike' 'land') 3}}"
}

Example generated response:

{
  "owns-list": ["bike","land"],
  "owns-string": "land,bike,boat,house"
}