DataPower API Gateway only

Constructing JSONata expressions to redact fields

To define a field for redaction or removal when using the Redaction policy with the DataPower® API Gateway, you supply a JSONata expression that defines the path to the field that you want to redact or remove.

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)
  • 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 JSONata numeric operators:

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

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

  • =
  • !=
  • <
  • >
  • <=
  • >=

You can define the path in either of the following ways:

Using a JSONata expression

The path specified by the JSONata expression is relative to any value specified for the root property of the Redaction policy. If the root property has no value or is absent, begin the expression with the absolute content path. If the root property has a value then you can either begin the expression with $ to use the root path directly, or you can provide a sub-path relative to the root path.

JSONata expressions can be used with content that is in either JSON or XML format.

Example 1
If the root property of the Redaction policy has no value or is absent, use the following expression to redact or remove all occurrences of the price field in the request and response data:
message.body.**.price
Example 2
If the root property of the Redaction policy has the value log.request_body, use the following expression to redact or remove all occurrences of the price field, specifically within an item element, in the logged request payload:
$.item.price
Example 3
If the root property of the Redaction policy has the value log, use the following expression to redact or remove all occurrences of the price field in the logged response payload:
response_body.**.price

The ** descendant wildcard traverses all descendants at all hierarchical levels.

Using the $xpath() JSONata extension

The $xpath() function has the following format:
$xpath(content_path, xpath_expression)
where:
  • content_path is the path to the content that contains the field that you want to redact or remove.
  • xpath_expression is the XPath expression that defines the field that you want to redact or remove.

The content_path is relative to any value specified for the root property of the Redaction policy. If the root property has no value or is absent, provide the absolute content path. If the root property has a value then you can either provide the value $ for the content_path parameter to use the root path directly, or you can provide a sub-path relative to the root path.

The $xpath() function can be used only with content that is in XML format.

Example 1
If the root property of the Redaction policy has no value or is absent, use the following expression to redact or remove all occurrences of the price field in the request and response data:
$xpath(message.body, '//price')
Example 2
If the root property of the Redaction policy has the value log.request_body, use the following expression to redact or remove all occurrences of the price field, specifically within an item element, in the logged request payload:
$xpath($, 'item/price')
Example 3
If the root property of the Redaction policy has the value log, use the following expression to redact or remove all occurrences of the price field in the logged response payload:
$xpath(response_body, '//price')

The // expression in the second parameter selects all occurrences anywhere in the content.