# How to apply JOLT for JSON transformations

**JOLT** (JSON Language for Transform) is a specification-based tool used to transform JSON data structures. On the Digibee Integration Platform, you can use JOLT within pipelines or capsules via the [**Transformer (JOLT)**](https://app.gitbook.com/s/EKM2LD3uNAckQgy1OUyZ/connectors/tools/jolt-v2) connector to extract and manipulate specific data from JSON payloads.

## **How JOLT works**

A JOLT specification typically consists of two main elements:

* `operation`: Defines the type of transformation to apply (`shift`, `remove`, `default`, and others).
* `spec`: Specifies the transformation rules applied according to the selected operation.

Transformations are written inside an array so that multiple operations can be chained and applied in sequence:

{% code expandable="true" %}

```json
[ 
 { 
   "operation": "", 
   "spec": { 
      "client.name": "customer.fullName" 
   } 
 } 
]
```

{% endcode %}

**Syntax elements:**

* `[ ]` (square brackets): Used to define arrays, such as when chaining multiple transformations.
* `{ }` (curly braces): Used to define JSON objects and key-value mapping within the spec.
* `.` (dot notation): Used to define nested paths in the output JSON. For example, `“client.name”: “customer.fullName”` maps a value to a nested field under `customer`.

{% hint style="success" %}
**Tip:** You can combine different operations in one transformation, like this:

```json
[
  {
    "operation": "shift",
    "spec": {
      "client.name": "customer.fullName"
    }
  },
  {
    "operation": "remove",
    "spec": ["client.ssn"]
  }
]
```

{% endhint %}

## **JOLT operations: Basic vs. Advanced**

JOLT defines the type of transformation through operations. Here are the most commonly used ones:

* `shift`: Restructures the JSON or renames fields.
* `default`: Inserts default values if fields are missing.
* `remove`: Deletes specific fields.
* `sort`: Arranges fields in alphabetical order.

JOLT also includes more **advanced operations**, such as:

* `modify-default-beta`: Sets default values without creating new fields — it only fills existing ones when they are empty or null.
* `modify-overwrite-beta`: Updates values using expressions or calculations.
* `cardinality`: Converts between objects and arrays.

## **Quickstart: Create your first transformation**

Use the `shift` operation to restructure a JSON object without modifying its values. This operation works by mapping fields from the input JSON to new locations in the output JSON. You define **where to find the values** in the original structure and **where to place them** in the new one.

### **Use case**

This transformation restructures a client record into a new format expected by another system. The input JSON contains flat fields inside `"client"`, while the target JSON organizes the data under `"customer"`, renames some fields, nests the address information, and duplicates the phone number into two different fields (`"phoneNumber"` and `"mobileNumber"`).

### **Step-by-step**

{% stepper %}
{% step %}

#### **Add the connector**

Open the pipeline and add a [**Transformer (JOLT) V2**](https://app.gitbook.com/s/EKM2LD3uNAckQgy1OUyZ/connectors/tools/jolt-v2) right after the trigger.
{% endstep %}

{% step %}

#### **Configure the transformation**

Paste the following spec into the connector’s configuration form:

{% code expandable="true" %}

```json
[
 {
   "operation": "shift",
   "spec": {
     "client": {
       "name": "customer.fullName",
       "birthDate": "customer.birthDate",
       "address": "customer.address.street",
       "country": "customer.address.country",
       "number": ["customer.phoneNumber", "customer.mobileNumber"]
     }
   }
 }
]
```

{% endcode %}

**What each mapping does:**

* **`"name": "customer.fullName"`**: Moves the value from `client.name` to `customer.fullName`.
* **`"birthDate": "customer.birthDate"`**: Copies the birth date to the new structure without changing its format.
* **`"address": "customer.address.street"`**: Takes the original flat `address` field and nests it under `customer.address.street`.
* **`"country": "customer.address.country"`**: Nests the country field inside the same `customer.address` object.
* **`"number": ["customer.phoneNumber", "customer.mobileNumber"]`**: Duplicates the `number` value, creating two separate fields: `phoneNumber` and `mobileNumber`.

{% hint style="info" %}
Only the fields explicitly mapped in the transformation spec will appear in the result. All other data from the input is excluded.
{% endhint %}
{% endstep %}

{% step %}

#### **Use this input JSON**

Copy this input and paste it into **Payload** on the Execution Panel.

{% code expandable="true" %}

```json
{ 
 "client": { 
   "name": "Sample Client", 
   "email": "sample-client@email.com", 
   "ssn": "123.456.789.10", 
   "birthDate": "02/15/1985", 
   "address": "Sample Client street, 123",
   "country": "United States",
   "number": "8888-8888"
 } 
}
```

{% endcode %}
{% endstep %}

{% step %}

#### **Run the test**

Click **Play** to run the test. You should see the following output:

{% code expandable="true" %}

```json
{
 "customer" : {
   "fullName" : "Sample Client",
   "birthDate" : "02/15/1985",
   "address" : {
     "street" : "Sample Client street, 123",
     "country" : "United States"
   },
   "phoneNumber" : "8888-8888",
   "mobileNumber" : "8888-8888"
 }
}
```

{% endcode %}
{% endstep %}
{% endstepper %}

## **Deepen your knowledge**

Now that you’re familiar with the basic JOLT concepts, you can explore additional operations. Check out our articles on creating [**basic JOLT transformations**](https://docs.digibee.com/documentation/resources/use-cases/how-to-jolt/basic-operations), using [**JOLT operators**](https://docs.digibee.com/documentation/resources/use-cases/how-to-jolt/operators), and building [**advanced transformations**](https://docs.digibee.com/documentation/resources/use-cases/how-to-jolt/advanced-operations). You can also browse real examples in [**Applying JOLT to practical use cases**](https://docs.digibee.com/documentation/resources/use-cases/how-to-jolt/use-cases) for inspiration.