> For the complete documentation index, see [llms.txt](https://docs.onum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onum.com/pipelines/actions/transformation/json-transformation.md).

# JSON Transformation

{% hint style="info" %}
See the changelog of this Action type [here](/actions-changelog/json-transformation.md).
{% endhint %}

## Overview

The **JSON** **Transformation** Action modifies your input JSON values using one of the given operations.

{% hint style="warning" %}
In order to configure this Action, you must first link it to a Listener. Go to [Building a Pipeline ](/pipelines/building-a-pipeline.md)to learn how to link.
{% endhint %}

## Ports

These are the input and output ports of this Action:

<details>

<summary>Input ports</summary>

* **Default port** - All the events to be processed by this Action enter through this port.

</details>

<details>

<summary>Output ports</summary>

* **Default port** - Events are sent through this port if no error occurs while processing them.
* **Error port** - Events are sent through this port if an error occurs while processing them.

</details>

## Configuration

{% stepper %}
{% step %}
Find **JSON Transformation** in the **Actions** tab (under the **Transformation** group) and drag it onto the canvas.
{% endstep %}

{% step %}
To open the configuration, click the Action in the canvas and select **Configuration**.
{% endstep %}

{% step %}
Enter the required parameters:

<table><thead><tr><th width="173.21875">Parameter</th><th>Description</th><th data-hidden></th></tr></thead><tbody><tr><td><strong>Select field to transform</strong></td><td>Select the field containing the JSON values from the incoming data. A sample input JSON is in the code box below.</td><td></td></tr><tr><td><strong>Select operation</strong></td><td><p>Select the operation to perform on your JSON field:<br></p><ul><li><p><strong>JQ</strong> - Performs a jq query on your input JSON values. Enter the following:</p><ul><li><strong>Query Expression</strong> - Enter the required jq expression. Note that the jq syntax has some limitations when you use it in this operation. Learn more in the note below.</li></ul></li><li><p><strong>Flat JSON</strong> - Converts a nested JSON into a new, flattened JSON field with only one layer of key/value pairs. Enter the following:</p><ul><li><strong>Flatten level</strong> - Set the maximum number of levels to flatten to. </li><li><strong>Choose an option</strong> - Choose to separate values with <em><code>_</code></em> or <em><code>.</code></em> (<em><code>_</code></em> by default.</li></ul></li></ul></td><td></td></tr><tr><td><strong>Output field</strong></td><td>Give your output field a name. You will see the transformation of the sample input JSON after applying the selected operation in the box below.</td><td></td></tr></tbody></table>

{% endstep %}

{% step %}
Click **Save** to complete the process.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**JQ syntax limitations**

Note that the JQ language has some limitations in Onum:

* The following jq operations are not supported: `get_jq_origin`, `get_prog_origin`, `get_search_list` , `input_line_number` and `$__loc__`
* The following jq flags are not supported: `--ascii-output, -a`, `--seq`, `--sort-keys, -S` and `--unbuffered`&#x20;
* JSON extensions cannot be parsed (`NaN`, `Infinity` and `[000]`).
* Some regular expression metacharacters, back references, and look-around assertions are not supported.
* Byte-order mark (BOM) is not supported.
* Keywords cannot be used as function names.
* Module name prefixes cannot be used in function declarations.
  {% endhint %}

## Examples

Check below an example with the different JSON operations available:

<details>

<summary>JQ</summary>

Suppose you want to apply a specific jq query to the JSON values in your input events. In this case, we need to get only the names from the values in our JSONs.

#### Raw JSON <a href="#raw-json" id="raw-json"></a>

Your input data contains the following raw JSON file in the `msg` field:

```json
[
   {
      "name":"Alice",
      "age":30
   },
   {
      "name":"Bob",
      "age":25
   },
   {
      "name":"Carol",
      "age":35
   }
]
```

#### Flat JSON <a href="#flat-json" id="flat-json"></a>

Add the **JSON Transformation** Action to the canvas and enter the following:

* **Field to transform -** `msg`
* **Select operation** - `JQ`
  * **Query expression** - `'.[].name'`
* **Out field** -  `JQvalue`

#### Results <a href="#results" id="results"></a>

The output field `JQvalue` will return the results after applying the specified JQ query:

```jq
[
   "Alice",
   "Bob",
   "Carol"
]
```

</details>

<details>

<summary>Flat JSON</summary>

Suppose you wish to flatten a JSON value in your input events.

#### Raw JSON <a href="#raw-json" id="raw-json"></a>

Your input data contains the following raw JSON file in the `msg` field:

```json
{
   "name":John,
   "age":30,
   "address":{
      "street":"123 Main St",
      "city":"Anytown",
      "country":"USA"
   },
   "contacts":[
      {
         "type":"email",
         "value":"john.doe@example.com"
      },
      {
         "type":"phone",
         "value":"555-1234"
      }
   ]
}
```

#### Flat JSON <a href="#flat-json" id="flat-json"></a>

Add the **JSON Transformation** Action to the canvas and enter the following:

* **Field to transform -** `msg`
* **Select operation** - `FlatJSON`
  * **Flatten level** - `5`
  * **Separator** - `.`
* **Out field** - `Flattened`

#### Results <a href="#results" id="results"></a>

The output field `Flattened` will return the JSON value flattened to a maximum level-5 hierarchy:

```json
{
   "name":John,
   "age":30,
   "address.street":"123 Main St",
   "address.city":"Anytown",
   "address.country":"USA",
   "contacts[0].type":"email",
   "contacts[0].value":"john.doe@example.com",
   "contacts[1].type":"phone",
   "contacts[1].value":"555-1234"
}
```

</details>