Mapping array fields

Introduction

This page provides guidance on mapping array fields, where the value from another field needs to be added to the array output.

To achieve this, wildcard (*) syntax is used to navigate and transform the JSON structure. Each asterisk represents a level in the data hierarchy, so you can copy values from parent objects into nested array elements without explicitly naming field names.

When an asterisk encounters an array, it means apply to every element in the array. This enables you to propagate data from higher levels down into all elements within nested arrays.

Need to know

• Each asterisk (*) represents one level of depth in the JSON structure.

• When an asterisk encounters an array, it applies to every element in that array.

• Field names are used to navigate to specific elements in the structure.

• The pattern reads from left to right, with each component specifying the next step in the traversal.

• Values are copied from higher levels down to lower levels, not moved or deleted from their original location

Example 1 (top-level array)

Consider the example below:

{
  "category": 1111,
  "fruit": [
    {
      "sku": "apples",
      "qty": 2
    },
    {
      "sku": "pears",
      "qty": 2
    }
  ]
}

We can map the fruit field very simply, as below:

Mapping rule

Output

{
  "fruit": [
    {
      "sku": "apples",
      "qty": 2
    },
    {
      "sku": "pears",
      "qty": 2
    }
  ]
}

The problem

Suppose we want to add the category field value to each item in the array, so the output is as shown below:

{
  "fruit": [
    {
      "sku": "apples",
      "qty": 2,
      "category": 1111
    },
    {
      "sku": "pears",
      "qty": 2,
      "category": 1111
    }
  ]
}

The solution

We can achieve this with the mapping rules below:

These rules can be summarised as follows:

Mapping rule	Summary
fruit ➤ fruit	The field mapping sequence matters. Before we can add a field value to another element, that element must be mapped. In this example, we need to add the category value to each item in the fruit array, so we map the fruit field first.
category ➤ *.*.*.category	The field name to add/update in each item. Here we use wildcards to traverse the JSON structure.

JSON traversal

The *.*.*.category target mapping traverses the JSON structure as follows:

Expression	JSON traversal
*	Start at the root: {category: 1111, fruit:[...]}
*	Enter the fruit array.
*	Access every item in the fruit array: {"sku": "apples","qty": 2},{"sku": "pears","qty": 2}
category	Add the category value (1111) to each array item.

Example 2 (nested array)

Consider the example below:

{
  "category": 1111,
  "fruit": [
    {
      "sku": "apples",
      "qty": 2,
      "options":[{"type:":"pink lady"},{"type:":"granny smith"},{"type:":"russet"}]
    },
    {
      "sku": "pears",
      "qty": 2,
      "options":[{"type:":"conference"},{"type:":"blush gold"}]
    }
  ]
}

The problem

Suppose we want to add the category field value to each item in the second array (options), so the output is as shown below:

{
  "fruit": [
    {
      "sku": "apples",
      "qty": 2,
      "options": [
        {
          "type:": "pink lady",
          "category": 1111
        },
        {
          "type:": "granny smith",
          "category": 1111
        },
        {
          "type:": "russet",
          "category": 1111
        }
      ]
    },
    {
      "sku": "pears",
      "qty": 2,
      "options": [
        {
          "type:": "conference",
          "category": 1111
        },
        {
          "type:": "blush gold",
          "category": 1111
        }
      ]
    }
  ]
}

The solution

We can achieve this with the mapping rules below:

These rules can be summarised as follows:

Mapping rule	Summary
fruit ➤ fruit	The field mapping sequence matters. Before we can add a field value to another element, that element must be mapped. In this example, we need to add the category value to each item in the fruit array, so we map the fruit field first.
category ➤ *.*.*.options.*.category	The field name to add/update in each item. Here we use wildcards to traverse the JSON structure.

JSON traversal

The *.*.*.options.*.category target mapping traverses the JSON structure as follows:

Expression	JSON traversal
*	Start at the root: {category: 1111, fruit:[...]}
*	Enter the fruit array.
*	Access every item in the fruit array: {"sku": "apples","qty": 2},{"sku": "pears","qty": 2, options: [...]}
options	Access the options array in each fruit item.
*	Apply to all items in the options array.
category	Add the category value (1111) to each options array item.

Related pages

• The array join transform function