How to apply JOLT for JSON transformations

Learn how JOLT works as a tool for transforming JSON data and how to use it on the Digibee Integration Platform.

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) 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:

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

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.

Tip: You can combine different operations in one transformation, like this:

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

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

1

Add the connector

Open the pipeline and add a Transformer (JOLT) V2 right after the trigger.

2

Configure the transformation

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

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

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.

Only the fields explicitly mapped in the transformation spec will appear in the result. All other data from the input is excluded.

3

Use this input JSON

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

{ 
 "client": { 
   "name": "Sample Client", 
   "email": "[email protected]", 
   "ssn": "123.456.789.10", 
   "birthDate": "02/15/1985", 
   "address": "Sample Client street, 123",
   "country": "United States",
   "number": "8888-8888"
 } 
}

4

Run the test

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

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

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, using JOLT operators, and building advanced transformations. You can also browse real examples in Applying JOLT to practical use cases for inspiration.