
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.
JSONata support in API Connect
API Connect supports v2.0 of the JSONata specification, with the following limitations:
- If you use a JSONata expression to extract or redact fields, soft linked copies of the field are also affected by the Extract or Redaction policy, even if the fields exist in different locations.
- API Connect does not support higher order JSONata functions (functions that process other functions).
- If a JSONata function supported by API Connect calls a higher order function as an argument, that argument is not supported (due to the lack of support for higher order functions).
- The following JSONata v2.0 functions are not supported:
$eval()
$sift()
$each()
$error()
$assert()
$fromMillis()
is supported with the following restrictions:- The
$fromMillis()
parameter supports numbers in the range -5364662400000 - 2903299199000.- A value less than -5364662400000 uses -5364662400000. In other words, reports the timestamp as 1800-01-01T00:00:00Z.
- A value greater than 2903299199000 uses 2903299199000. In other words, reports the timestamp as 2261-12-31T23:59:59Z.
- The
$now()
is supported with the following restrictions:- The following component specifiers are not supported:
W
= Week in yearw
= Week in monthX
= ISO week-numbering yearx
= ISO week-numbering month
- Representing numbers as words are not supported, so the following presentation modifiers are not supported:
W
= Uppercase word (for example: [YW] => TWO THOUSAND AND TWENTY-FOUR)w
= Lowercase word (for example: [Yw] => two thousand and twenty-four)Ww
= Title case word (for example: [YWw] => Two Thousand and Twenty-Four)
- Error messages are generic.
- The following component specifiers are not supported:
Table 1 lists the functional extensions that you can use with standard JSONata notation. Each extension corresponds to a part of the API context.
Extension | Variable | Description |
---|---|---|
$apiCtx() |
Generic access to an API context | The $apiCtx() extension gives generic access to an API context.
|
$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') |
|
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 |
Storage type of the message. The supported values are binary ,
empty , graphql , json , stream , or
xml . |
$urlParameter('name') |
|
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.
The
$urlParameter('breed') URL returns the following array of
values.
In this example, the URL includes
an API path that is configured as |
$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.
|
Table 2 lists the functional extensions that you can use with GraphQL APIs.
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:
=
!=
<
>
<=
>=
- 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.
query
The entire GraphQL query including operations and fragments.
operationName
For an anonymous operation,
operationName
can be empty.~fragmentSpreadName
on~typeCondition
- ~~
fragmentDefinitionName
You can define the path using either of the following options:
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 theprice
field in the request and response data:message.body.**.price
- Example 2
- If the
root
property of the Redaction policy has the valuelog.request_body
, use the following expression to redact or remove all occurrences of theprice
field, specifically within anitem
element, in the logged request payload:$.item.price
- Example 3
- If the
root
property of the Redaction policy has the valuelog
, use the following expression to redact or remove all occurrences of theprice
field in the logged response payload:response_body.**.price
The **
descendant wildcard traverses all descendants at all hierarchical
levels.
Using the $xpath()
JSONata extension
$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 theprice
field in the request and response data:$xpath(message.body, '//price')
- Example 2
- If the
root
property of the Redaction policy has the valuelog.request_body
, use the following expression to redact or remove all occurrences of theprice
field, specifically within anitem
element, in the logged request payload:$xpath($, 'item/price')
- Example 3
- If the
root
property of the Redaction policy has the valuelog
, use the following expression to redact or remove all occurrences of theprice
field in the logged response payload:$xpath(response_body, '//price')
The //
expression in the second parameter selects all occurrences anywhere in
the content.