# 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)**](/documentation/connectors-and-triggers/connectors/tools/jolt-v2.md) 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**](/documentation/connectors-and-triggers/connectors/tools/jolt-v2.md) 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**](/documentation/resources/use-cases/how-to-jolt/basic-operations.md), using [**JOLT operators**](/documentation/resources/use-cases/how-to-jolt/operators.md), and building [**advanced transformations**](/documentation/resources/use-cases/how-to-jolt/advanced-operations.md). You can also browse real examples in [**Applying JOLT to practical use cases**](/documentation/resources/use-cases/how-to-jolt/use-cases.md) for inspiration.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digibee.com/documentation/resources/use-cases/how-to-jolt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.