JSON API

The context object have one method called jsonAPI() that returns an API object for various JSON related tasks.

Examples:

Deserialize a string into an object structure
Serialize an object into a JSON string
Evaluate JSON path expressions
Evaluate JSON ata expressions

The JavaScript language itself provides some alternative methods for deserialization and serialization of objects to and from JSON strings.

These are available via the global JSON object.

Deserialize JSON String

Alternative 1: Use JSON API.

const string = '{"pi":3.14}';
const obj = JSON.parse(string);
const pi = obj.pi;

Alternative 2: Use context.jsonAPI()

const string = '{"pi":3.14}';
const obj = context.jsonAPI().readValue(string);
const pi = obj.pi;
// or
const typedObj = context.jsonAPI().readValue(string, java.util.Map.class);

Serialize Object to String

Alternative 1: Use the JSON API.

const str = JSON.stringify({
    result: 'Succeeded',
    status: 'Engineering item updated'
});

Alternative 2: Use the context.jsonAPI().

const obj = {"pi":3.14};
const str = context.jsonAPI().serialize(string);
const pi = obj.pi;
// or
const typedObj = context.jsonAPI().readValue(string, java.util.Map.class);

JSON Path Evaluation

let obj = {
  items: [
      {
          id: 'item1',
          name: 'name1',
          weight: 194
      },
      {
          id: 'item2',
          name: 'name2',
          weight: 13
      },
  ]
};
let evaluator = context.jsonAPI().jsonPath(obj);
let weights = evaluator.evaluate('$.items[*].weight');
console.log('%o', weights); // logs: 194,13

JSONata Evaluation

const data = {
        "Account": {
            "Account Name": "Firefly",
            "Order": [{
                    "OrderID": "order103",
                    "Product": [{
                            "Product Name": "Bowler Hat",
                            "ProductID": 858383,
                            "SKU": "0406654608",
                            "Description": {
                                "Colour": "Purple",
                                "Width": 300,
                                "Height": 200,
                                "Depth": 210,
                                "Weight": 0.75
                            },
                            "Price": 34.45,
                            "Quantity": 2
                        },
                        {
                            "Product Name": "Trilby hat",
                            "ProductID": 858236,
                            "SKU": "0406634348",
                            "Description": {
                                "Colour": "Orange",
                                "Width": 300,
                                "Height": 200,
                                "Depth": 210,
                                "Weight": 0.6
                            },
                            "Price": 21.67,
                            "Quantity": 1
                        }
                    ]
                },
                {
                    "OrderID": "order104",
                    "Product": [{
                            "Product Name": "Bowler Hat",
                            "ProductID": 858383,
                            "SKU": "040657863",
                            "Description": {
                                "Colour": "Purple",
                                "Width": 300,
                                "Height": 200,
                                "Depth": 210,
                                "Weight": 0.75
                            },
                            "Price": 34.45,
                            "Quantity": 4
                        },
                        {
                            "ProductID": 345664,
                            "SKU": "0406654603",
                            "Product Name": "Cloak",
                            "Description": {
                                "Colour": "Black",
                                "Width": 30,
                                "Height": 20,
                                "Depth": 210,
                                "Weight": 2
                            },
                            "Price": 107.99,
                            "Quantity": 1
                        }
                    ]
                }
            ]
        }
    };
    const ata = '$sum(Account.Order.Product.(Price * Quantity))';
    const evaluator = api.jsonAta(ata);
    const result = evaluator.evaluate(data); // 336.36

JSONata vs JSONPath

Whats the main difference among JSONata and JSONPaths?

Both are ways to query/transform JSON, but they serve different purposes:

JSONPath — Query language

Think of it like XPath but for JSON. It’s designed to select and extract values from a JSON document.

// Given: { "store": { "books": [{"title": "A"}, {"title": "B"}] } }

$.store.books[*].title     // → ["A", "B"]
$.store..price             // → all prices (recursive descent)
$.store.books[?(@.price < 10)]  // → filter expression

Characteristics:

Read-only - Selects data, doesn’t transform it
Simple syntax, Close to dot-notation you already write
Standardized (RFC 9535 as of 2024)

JSONata — Expression & transformation language

Think of it like SQL meets XPath meets a functional language. It can query, reshape, compute, and transform JSON into entirely new structures.

// Same data, but now transforming it:
store.books.title           // same selection as above

// But also:
$sum(store.books.price)     // aggregate functions
store.books.{ "name": title, "cost": price * 1.2 }  // reshape output
store.books[price < 10].title  // filter + select
$join(store.books.title, ", ")  // string operations

Characteristics:

Read + transform — outputs can be completely different shapes
Has functions, operators, conditionals, lambdas
Can produce scalars, arrays, objects — whatever you need
Used heavily in Node-RED, IBM App Connect, MuleSoft, WSO2
Not standardized (one reference implementation, maintained by IBM/Jsonata.org)

Rule of thumb: if you just need to pluck a value out of JSON, JSONPath is simpler.