Construction

Construction

Article Type: How-To Audience: Developers, App Admins Module: How To

So far, we have discovered how to extract values from a JSON document, and how to manipulate the data using numeric, string and other operators. It is also useful to be able to specify how this processed data is presented in the output — by building result structures with JSONata's array and object constructors.

Array Constructors

As previously observed, when a location path matches multiple values in the input document, these values are returned as an array. The values might be objects or arrays, and as such will have their own structure, but the matched values themselves are at the top level in the resultant array.

It is possible to build extra structure into the resultant array by specifying the construction of arrays (or objects) within the location path expression. At any point in a location path where a field reference is expected, a pair of square brackets [] can be inserted to specify that the results of the expression within those brackets should be contained within a new array in the output. Commas are used to separate multiple expressions within the array constructor.

Array constructors can also be used within location paths for making multiple selections without the broad-brush use of wildcards.

Examples

The four email addresses are returned in a flat array:

Email.address

[
  "fred.smith@my-work.com",
  "fsmith@my-work.com",
  "freddy@my-social.com",
  "frederic.smith@very-serious.com"
]

Each email object generates an array of addresses:

Email.[address]

[
  [ "fred.smith@my-work.com", "fsmith@my-work.com" ],
  [ "freddy@my-social.com", "frederic.smith@very-serious.com" ]
]

Selects the City value of both Address and Alternative.Address objects:

[Address, Other.`Alternative.Address`].City

[ "Winchester", "London" ]

Object Constructors

In a similar manner to the way arrays can be constructed, JSON objects can also be constructed in the output. At any point in a location path where a field reference is expected, a pair of braces {} containing key/value pairs separated by commas, with each key and value separated by a colon: {key1: value1, key2: value2}. The keys and values can either be literals or expressions. The key must either be a string or an expression that evaluates to a string.

When an object constructor follows an expression that selects multiple values, the object constructor will create a single object that contains a key/value pair for each of those context values. If an array of objects is required (one for each context value), then the object constructor should immediately follow the dot . operator.

Examples

Produces an array of objects (one for each phone):

Phone.{type: number}

[
  { "home": "0203 544 1234" },
  { "office": "01962 001234" },
  { "office": "01962 001235" },
  { "mobile": "077 7700 1234" }
]

Combines the key/value pairs into a single object (see Sorting-Grouping-and-Aggregation for more details on grouping using object key expressions):

Phone{type: number}

{
  "home": "0203 544 1234",
  "office": [
    "01962 001234",
    "01962 001235"
  ],
  "mobile": "077 7700 1234"
}

Combines the key/value pairs into a single object — in this case, for consistency, all numbers are grouped into arrays (see Predicate-Expressions for details on singleton array and value equivalence):

Phone{type: number[]}

{
  "home": [
    "0203 544 1234"
  ],
  "office": [
    "01962 001234",
    "01962 001235"
  ],
  "mobile": [
    "077 7700 1234"
  ]
}

JSON Literals

The array and object constructors use the standard JSON syntax for JSON arrays and JSON objects. In addition, values of the other JSON data types can be entered into an expression using their native JSON syntax:

• Strings — "hello world"
• Numbers — 34.5
• Booleans — true or false
• Nulls — null
• Objects — {"key1": "value1", "key2": "value2"}
• Arrays — ["value1", "value2"]

JSONata is a superset of JSON. This means that any valid JSON document is also a valid JSONata expression. This property allows you to use a JSON document as a template for the desired output, and then replace parts of it with expressions to insert data into the output from the input document.

See Also

• Jsonata-Tutorial
• Constructs
• Predicate-Expressions
• Sorting-Grouping-and-Aggregation
• Composition

---

Source: support.fuuz.com