There are 7 methods built in the JSONata function library I tend to use all the time when transforming JSON.
$contains()
This function checks if a string contains a substring or matches a regular expression, and returns true or false (no match).
Example usage
// JSON input
{
"postcode": "LS1 2AB"
}
/* JSONata expressions */
(
$contains($.postcode, "LS1"); /* => true */
$contains($.postcode, "LS12"); /* => false */
$contains($.postcode, /LS1\s?2/); /* => true */
$contains($.postcode, /AB$/); /* => true */
)
$join()
This function combines an array of strings into one, and accepts an optional separator as a second argument.
Example usage
// JSON input
{
"firstName": "John",
"lastName": "Doe"
}
/* JSONata expressions */
(
$join([$.firstName, " ", $.lastName]); /* => "John Doe" */
$join(["Hello", $.firstName, $.lastName], " "); /* => "Hello John Doe" */
)
$exists()
This boolean function takes in an expression and returns true if the expression evaluates to a value, or false if otherwise.
Example usage
// JSON input
{
"firstName": "John",
"lastName": "Doe",
"age": 31
}
/* JSONata expressions */
(
$exists($.age); /* => true */
$exists($.middleName); /* => false (no match) */
)
$count()
This function returns the number of items in a given array.
Example usage
// JSON input
{
"firstName": "John",
"phones": [
{ "type": "home", "value": "1234" },
{ "type": "mobile", "value": "5678" },
{ "type": "mobile", "value": "91011" }
]
}
/* JSONata expressions */
(
$count($.phones); /* => 3 */
$count($.phones[type = "mobile"]); /* => 2 */
)
$distinct()
This function is ideal for removing duplicates from an array.
Example usage
// JSON input
[
{
"user": "John",
"country": "UK"
},
{
"user": "George",
"country": "UK"
},
{
"user": "Sarah",
"country": "USA"
},
{
"user": "Robert",
"country": "Canada"
}
]
/* JSONata expressions */
(
$countries := $.country; /* => ["UK","UK","USA","Canada"] */
$distinct($countries); /* => ["UK","USA","Canada"] */
)
$map()
This function is essential for applying a consistent change to all items of an array, and returns the modified array.
Example usage
// JSON input
{
"firstName": "John",
"phones": [
{
"type": "home",
"value": "1234",
"countryCode": "44"
},
{
"type": "mobile",
"value": "5678",
"countryCode": "44"
},
{
"type": "mobile",
"value": "91011",
"countryCode": "44"
}
]
}
/* JSONata expression */
$map($.phones, function($v) {
$join(["+", $v.countryCode, $v.value])
}) /* => ["+441234","+445678","+4491011"] */
$filter()
This function filters an array based on a boolean condition, and returns all items of the array that meet the condition.
Example usage
// JSON input
{
"firstName": "John",
"phones": [
{
"type": "home",
"value": "1234",
"countryCode": "44",
"description": "Personal home number"
},
{
"type": "mobile",
"value": "5678",
"countryCode": "44",
"description": "Mobile number in the UK"
},
{
"type": "mobile",
"value": "91011",
"countryCode": "49",
"description": "Mobile number in Germany"
}
]
}
/* JSONata expression */
$filter($.phones, function($v) {
$v.type = "mobile" and $v.countryCode = "49"
})
/* =>
{
"type": "mobile",
"value": "91011",
"countryCode": "49",
"description": "Mobile number in Germany"
}
*/