Sample JSONata expressions

Sample JSONata expressions to illustrate its powerful mapping capabilities within z/OS® Connect Designer.

zosConnect-3.0 Applies to zosConnect-3.0.

The following examples illustrate some of the powerful mapping functions of JSONata. Use part of, all of or even combine the samples to meet your mapping requirements; from basic mappings through to and including more complex mappings. To see what data is available to map, see How the z/OS Connect Server JSON object is created for mapping.

Important: {{ ... }} double braces must be used to identify the JSONata expression in fields of type String. The (abc) label identifies a string-mapping field. Any text outside the double braces {{ ... }} is treated as a string literal. All other field values are treated as JSONata expressions in which literal text should be quoted.

If you have an interesting mapping and would like to share it, click the and the . This opens the "Rate this content" window where there is a free text box for you to add any feedback comments and share your mapping to be included here.

String examples

Concatenate fields

Join together multiple fields with some text into a single value. For String (abc) fields, any text outside of double braces {{ ... }} is treated as a string literal.

Input

body

{
    "firstName": "JOHN",
    "lastName": "DOE",
    "middleInitial": "A",
    "age": 50
}

Mapping

{{$body.firstName}} {{$body.middleInitial}} {{$body.lastName}} is {{$body.age}} years old.

Output

"JOHN A DOE is 50 years old."

Convert a string to lowercase

To convert a string field to lowercase, use the lowercase function. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/string-functions#lowercase.

Input

body

{
    "firstName": "JOHN"
}

Mapping

{{$lowercase($body.firstName)}}

Output

"john"

Extract a substring

To extract part of a string field, use the substring function. This example shows how to extract the year part of a date field. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/string-functions#substring.

Input

body

{
    "date": "2022/05/20"
}

Mapping

{{$substring($body.date, 0, 4)}}

Output

"2022"

Capitalizing the first letter of a name

You can capitalize part of a string field. In this example, the first substring selects the first letter of the name. The second substring extracts everything except the first letter and then calls the lowercase function on the result. These two strings are then appended to each other. For more information about these functions, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/string-functions#substring.

Input

body

{
    "firstName": "JOHN"
}

Mapping

{{$substring($body.firstName, 0, 1)}}{{$lowercase($substring($body.firstName, 1))}}

Output

"John"

Numeric examples

Operators (`+-` `*` `/` `%` `..` )

For numerical operations, use the + (Addition), - (Subtraction/Negation), * (Multiplication), / (Division), % (Modulo), and .. (Range) operators in the mapping. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/numeric-operators.

Input

body

{
    "salary": 25280.0,
    "bonus": 500.0,
    "commission": 2022.0
}

Mapping

$body.salary + $body.bonus + $body.commission

Output

27802.0

Formatting numbers

To format a number, use the formatNumber function. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/numeric-functions#formatnumber.

Input

body

{
    "salary": 25280.0
}

Mapping

$formatNumber($body.salary, "##,###.00")

Output

25,280.00

Counting elements in an array

To count the number of elements in an array, use the count function. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/array-functions#count.

Input

body

["a", "b", "c"]

Mapping

$count($body)

Output

Date examples

Converting date format

To convert a date from one format to another, use the toMillis and fromMillis functions. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/date-time-functions.

Input

body

{
    "date": "13-04-2022"
}

Mapping

{{$fromMillis($toMillis($body.date, "[D01]-[M01]-[Y0001]"), "[D1o] [MNn] [Y0001]")}}

Output

"13th April 2022"

Converting time format

To convert a time from one format to another, use the toMillis and fromMillis functions. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/date-time-functions.

Input

body

{
    "time": "21:55:32"
}

Mapping

{{$fromMillis($toMillis($body.time, "[H01]:[m01]:[s01]"), "[h01]:[m01]:[s01] [PN]")}}

Output

"09:55:32 pm"

Boolean examples

Querying a field value for specific contents

To check whether a field value matches another, use the contains function. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/string-functions#contains.

Input

body

{
    "job": "designer"
}

Mapping

$contains($body.job, "designer")

Output

true

Comparing numbers for a Boolean result

To compare fields, use the comparison operators. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/comparison-operators.

Input

body

{
    "age": 50
}

Mapping

$body.age >= 18

Output

true

Conditional field value mapping

Comparing a fields value by using regular expressions

A regular expression can be used within the $contains function to do pattern matching conditions to determine how a field is mapped. This example uses a regular expression /^\s+$/ and a conditional ternary operator to match when the field $body.myField contains only spaces. When this expression returns true, the value “Default value” is assigned. When this expression returns false, the fields actual value is inserted. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/string-functions#contains and https://docs.jsonata.org/other-operators#--conditional.

Input

body

{
    "myField": "      "
}

Mapping

$contains($body.myField, /^\s*$/) ? "Default value" : $body.myField

Output

"Default value"

Setting a fields' value depending on the input value

A ternary operator can be used to decide how a field is mapped based on an input field. In this example, the field $body.customField has a value of either "0" or "1". When the value is "0" the field should be mapped to "N" and when the value is "1", the field should be mapped to "Y". By comparing the $body.customField value to "0", the true or false result determines the output value of either "N" or "Y".

Input

body

{
    "customField": "1"
}

Mapping

("0" = $body.customField ? "N" : "Y")

Output

"Y"

Other examples

Extracting field values from a JSON Web Token payload

A JWT header consists of three sections: header, payload, and signature. Each section is Base64 encoded and separated by dots (.). This example shows how to extract the payload, decode from Base64 , then get the value of the name field in the JSON:

Input

HTTP header named jwt:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The payload section of this JWT represents this JSON object (Base64 encoded):

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

Mapping

{{$eval($base64decode($split($headers.jwt, \"\\.\")[1])).name`}}

Output

"John Doe"

Explanation

The JWT header is split into three parts by using the split function, with a dot (.) as the separator, and the element at position 1 (the JWT payload) is selected.
Note: The dot must be escaped with a double backslash (\)
```
$split($headers.jwt,
          \"\\.\")[1]
```
The split command returns an array with three entries:
```
["eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ", "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"]
```
The element at index [1] is then selected.
```
"eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ"
```

This value is then Base64 decoded by using the base64decode function:

$base64decode($split($headers.jwt, \"\\.\")[1])

This returns the following payload

{ "sub": "1234567890", "name": "John Doe", "iat": 1516239022 }

The final value "John Doe" for the name field. This is extracted by first evaluating the string as a JSON object by using the $eval function, and then selecting the name field.
```
$eval($base64decode($split($headers.jwt, \"\\.\")[1])).name
```

Querying array elements based on field values

Given a JSON array of objects in the request body, it is possible to extract specific elements by field name. This example shows how to extract the value of the value field for the object with name matching "customerNumber".

Input

body

[
    {
        "name": "firstName",
        "value": "Joe"
    },
    {
        "name": "lastName",
        "value": "Blogs"
    },
    {
        "name": "customerNumber",
        "value": "123456"
    }
]

Mapping

{{$body["customerNumber" in name].value}}

Output

"123456"

Returning a specific string based on a boolean field being true, false, or not present

The conditional ternary operator can be used to decide on which value to return based on a boolean field having a value of true, false, or not being present in JSON. The conditional ternary operator can also be used for fields that are not boolean. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/other-operators#--conditional.

Input

body

{
    "isFree": true
}

Mapping

$exists($body.isFree) ? $body.isFree ? "Yes" : "No" : "Omitted"

Output

"Yes"

Explanation

The mapping first checks if $exists($body.isFree) expression evaluates as true or false. When true, the processing continues to step 2. When false, the value "Omitted" is returned.
If the $body.isFree field exists in the JSON, then the value of the field $body.isFree is evaluated in the next part of the mapping $body.isFree ? "Yes" : "No". When true, "Yes" is returned. When false, "No" is returned.

Enforcing Open API document defaults for request fields

Some Open API documents have default values for fields in the request body. As the request mapping panel cannot associate Open API fields with z/OS Asset request fields, it is necessary that the user enforces the Open API document default values through mappings. To ensure that these defaults are respected when a user calls an API, a JSONata conditional ternary operator can be used to evaluate whether the user provided a value for a field or if a default should be used instead. For more information, see A launch icon to indicate a link opens a new tab or window. https://docs.jsonata.org/other-operators#--conditional.

Input

body

{
  "firstName": "Joe",
  "lastName": "Blogs"
}

Mapping

$exists($body.department) ? $body.department : "STAFF"

Output

"STAFF"

Explanation

As the JSON body does not contain the field department the condition $exists($body.department) evaluates as false and the value "STAFF", which is the default from the Open API document, is returned. When department does exist, it is used.

Returning a subset of an Array based on a counter

An array can be truncated by a specified counter to work only with and return the number of items that are specified in the counter.

Input

body

{
    "itemCount": 3,
    "items": [
       "Pens",
       "Pencils",
       "Paper",
       "",
       "",
       ""
    ]
}

Mapping

($count := $itemCount; $items[[0..$count-1]])

Output

[ "Pens", "Pencils", "Paper" ]

Returning a subset of an Array based on the array items

An array can be truncated by returning only the items that meet a specific condition.

Input

body

{
   "items": [
      "Pens",
      "Pencils",
      "Paper",
      "",
      "",
      ""
   ]
}

Mapping

$filter($items, function($v) {$length($v) > 0})

Output

[ "Pens", "Pencils", "Paper" ]

Explanation

The mapping filters the array and returns only those elements that have a length greater than 0. For more information, see A launch icon to indicate a link opens a new tab or window.

https://docs.jsonata.org/higher-order-functions#filter

Sample JSONata expressions

String examples

Concatenate fields

Convert a string to lowercase

Extract a substring

Capitalizing the first letter of a name

Numeric examples

Operators (+- * / % .. )

Formatting numbers

Counting elements in an array

Date examples

Converting date format

Converting time format

Boolean examples

Querying a field value for specific contents

Comparing numbers for a Boolean result

Conditional field value mapping

Comparing a fields value by using regular expressions

Setting a fields' value depending on the input value

Other examples

Extracting field values from a JSON Web Token payload

Querying array elements based on field values

Returning a specific string based on a boolean field being true, false, or not present

Enforcing Open API document defaults for request fields

Returning a subset of an Array based on a counter

Returning a subset of an Array based on the array items

Operators (`+-` `*` `/` `%` `..` )