Constructing JSONata expressions to extract and transform data

To extract and transform data from fields in the API context when using the Extract policy with the DataPower® API Gateway, you supply a JSONata expression that defines the fields to extract and transform.

Note: For a list of known limitations to DataPower API Gateway support for JSONata, see Limitations to support for JSONata.

The following JSONata functions are supported:

Aggregation functions:
- $average(array)
- $max(array)
- $min(array)
- $sum(array)
Array functions:
- $append(array1, array2)
- $count(array)
- $reverse(array)
- $sort(array [, function])
- $zip(array1, ...)
Boolean functions:
- $boolean(arg)
- $exists(arg)
- $not(arg)
Numeric functions:
- $abs(number)
- $ceil(number)
- $floor(number)
- $formatBase(number [, radix])
- $number(arg)
- $power(base, exponent)
- $round(number [, precision])
- $sqrt(number)
Object functions:
- $keys(object)
- $lookup(object, key)
- $merge(array<object>)
- $spread(object)
- $type(value)
  In addition to the standard values returned by $type(), the API gateway implementation of $type() can return the following values: binary, empty, graphql, stream, or xml.
String functions:
- $contains(str, pattern)
- $join(array[, separator])
- $length(str)
- $lowercase(str)
- $match(str, pattern [, limit])
- $pad(str, width [, char])
- $replace(str, pattern, replacement [, limit])
- $split(str, separator [, limit])
- $string(arg)
- $substring(str, start[, length])
- $substringAfter(str, chars)
- $substringBefore(str, chars)
- $trim(str)
- $uppercase(str)

You can use the following functional extensions to standard JSONata notation. Each extension corresponds to a part of the API context.

Table 1. Functional extensions to JSONata
Extension	Variable	Description
`$header(name)`	`message.headers.name`	Message header
`$httpVerb()`	`request.verb`	HTTP method of the request
`$operationID()`	`api.operation.id`	ID of the operation
`$operationPath()`	`api.operation.path`	Path of the operation
`$queryParameter('name')`	`request.parameters.name.locations` The supported keyword is `query`. `request.parameters.name.values`	Searches for the index of `query` in `request.parameters.name.locations` and returns `request.parameters.name.values[index]`, where `[index]` is the value for `query` in locations. Parameter values are not URL decoded.
`$statusCode()`	`message.status.code`	Status code
`$storageType([arg])`	`variable.body` You can specify any variable in the API context. When no variable is specified, the default variable `message.body` is used.	Storage type of the message. The supported values are `binary`, `empty`, `graphql`, `json`, `stream`, or `xml`.
`$urlParameter('name')`	`request.parameters.name.locations` The supported keywords are `path` and `query` `request.parameters.name.values`	Searches for the index of `path` and `query` in `request.parameters.name.locations` and returns a single array that contains both `path` and `query` values from `request.parameters.name.values`. When the URL contains both path and query parameter values, the array includes the path values first followed by the query values. The values of each parameter type are added in the order that they are received. Parameter values are URL decoded. For example, the following URL contains both path and query parameter values. `http://example.com/petstore/cats/adopt?breed=Sphynx&breed=Siamese` The `$urlParameter('breed')` URL returns the following array of values. `[cats, adopt, Sphynx, Siamese]` In this example, the URL includes an API path that is configured as `/petstore/{breed}/{breed}`, where `breed` is configured to be a path parameter of the API path. As a result, `cats` and `adopt` are included in the output.
`$xpath(path, xpathExpression)`	You can specify any writable variable in the API context. The `xpathExpression` must be a literal string.	Allows use of XPath expressions. The following example specifies all price elements in the source. `$xpath($, '//price')`

Table 2. Functional extensions to JSONata for GraphQL
Extension	Variable	Description
`$gqlActiveOperation([graphql_message])`	`message.body`	Gets the active operation found in the specified GraphQL message. The `operationName` must be the same as the name of the active operation.
`$gqlAlias(graphql_field_node)`	`message.body`	Gets the alias of a GraphQL field node.
`$gqlFragments([graphql_message])`	`message.body`	Gets the fragments found in the specified GraphQL message.
`$gqlName([graphql_node])`	`message.body`	Gets the node name. For operations, the node name is the `operationName`. For fields, fragment definitions, arguments, and other elements, the node name is the name of the element. By default, the `operationName` of `message.body` is retrieved.
`$gqlOperations([graphql_message])`	`message.body`	Gets the operations found in the specified GraphQL message.
`$gqlType([graphql_node])`	`message.body`	The operation type of the active operation is retrieved for Query, Mutation, and Subscription query types.

You can use the & (concatenation) navigation operator.

You can use the following JSONata numeric operators:

+ (addition)
- (subtraction)
* (multiplication)
/ (division)
% (modulo)

You can use the following JSONata comparison operators for number values or strings:

=
!=
<
>
<=
>=

You can also use the following operators and expressions.

Parentheses to convert a sequence into an array, specify operator precedence, or compute complex expressions on a context value.
Array ranges and predicate expressions.
Single asterisk (*) and double asterisk (**) wildcard characters.

The following elements of a GraphQL query can be exposed in JSONata notation using the syntax shown.

query
The entire GraphQL query including operations and fragments.
operationName
For an anonymous operation, operationName can be empty.
~fragmentSpreadName
on~typeCondition
~~fragmentDefinitionName