Sort Syntax

The sort query parameter is available for GET requests on EMu based resources. The property defines the sort order matching records are to be returned in. The sort property value is a JSON array where each entry in the array defines a field to be sorted on and whether the field should be sorted in ascending or descending order.

The JSON format for the sort value can be described as:

[
  { "{column}" : { "order": "{asc|desc}" } },
  ...
]

The {column} property is a fully qualified column name including the envelope that matches a record. The envelope being:

{
  "id": "{id}",
  "version": {version},
  "data": {match}
}

If you wanted to sort on the NamLast field in the Parties module then the column name would be data.NamLast. If you wanted to sort on the id field then he column name would just be id. The order property has a value of either asc for ascending collation or desc for descending collation.

The sorting is multi-level where the first entry in the array defines the primary sort order and where two values are the same then the second entry is used and so on.

Since sort is a query parameter, it is part of the request URL. To conform with the list of acceptable characters in a URL, the sort value must be URL Encoded. All reserved and common characters must be percent encoded.

JSON Schema

The JSON Schema definition for the sort query property is:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "emu:/shared/resources/sort#",
  "title": "sort definitions",
  "description": "Definitions to validate sort option",
  "definitions": {
    "sort": {
      "type": "array",
      "items": {
        "patternProperties": {
          "^[a-zA-Z0-9_.]": {
            "type": "object",
            "properties": {
              "order": {
                "enum": [ "asc", "desc" ]
              }
            },
            "required": [ "order" ]
          }
        },
        "minProperties": 1,
        "maxProperties": 1
      }
    }
  },
  "anyOf": [
    {
      "$comment": "Required for sorting of matching records",
      "$ref": "#/definitions/sort"
    }
  ]
}