Applying JOLT to practical use cases

Learn how to turn JOLT operations into practical solutions.

JOLT is widely used in integrations to restructure JSON data, apply business rules, and prepare payloads for downstream systems. It allows you to transform information dynamically, ensuring that each pipeline receives data in the exact structure it needs.

In this guide, you'll find a collection of practical, real-world examples that illustrate how JOLT can solve common transformation challenges.

Hands-on examples

Each example includes:

• The Input JSON, demonstrating the original data structure.

• The desired output, showing the target format you want to achieve.

• The JOLT spec, which you can copy and reuse in your pipelines.

• A clear explanation that breaks down the transformation logic.

Together, these examples will help you build confidence in writing and adapting JOLT specifications for your integration use cases.

Separating a full name into first name and last name

This transformation extracts the first and last elements of a full name string and maps them into new fields.

Input JSON

{  
    "fullName": "Vitor Aquiles Sordi"
}

Desired output JSON

{  
    "name": "Vitor",  
    "lastName": "Sordi"
}

Transformation spec

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "fullName": "=split(' ',@(1,fullName))",
      "name": "=firstElement(@(1,fullName))",
      "lastName": "=lastElement(@(1,fullName))"
    }
  },
  {
    "operation": "remove",
    "spec": {
      "fullName": ""
    }
  }
]

Explanation

The full name is split into a list using spaces as separators. Then, the first and last elements of this list are extracted. The original fullName field is removed since it's no longer needed.

Separating the area code from a phone number

This transformation isolates the first two digits of a phone number (DDD) and extracts the remaining portion as the telephone number.

Input JSON

{  
    "telephone": "11999998888"
}

Desired output JSON

{  
    "ddd": "11",  
    "telephone": "999998888"
}

Transformation spec

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "ddd": "=substring(@(1,telephone),0,2)",
      "sizeTelehone": "=size(@(1,telephone))",
      "telephone": "=substring(@(1,telephone),2,@(1,sizeTelephone))"
    }
  },
  {
    "operation": "remove",
    "spec": {
      "sizeTelephone": ""
    }
  }
]

Explanation

For this type of transformation, and because of how the substring function works, we can define the start and end positions of the snippet we want to extract from a string.

However, phone numbers can vary in length. The telephone field may contain:

• A landline number

• A mobile number

• A formatted value such as "1199999-8888"

Because of these variations, we chose to use the function dynamically.

How we handle it:

1. We first calculate the size of the value in telephone.

2. We then pass that size as a parameter to the substring function.

This approach avoids any dependency on the string length and ensures we always extract the last character, regardless of the input format.

Removing special characters from CPF and CNPJ

This transformation removes punctuation and formatting characters from CPF and CNPJ fields.

Input JSON

{  
    "cpf": "123.456.789-10",  
    "cnpj": "11.222.333/0001-10"
}

Desired output JSON

{  
    "cpf": "12345678910",  
    "cnpj": "11222333000110"
}

Transformation spec

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "cpf": "=split('[.-]',@(1,cpf))",
      "cnpj": "=split('[./-]',@(1,cnpj))"
    }
  },
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "cpf": "=join('',@(1,cpf))",
      "cnpj": "=join('',@(1,cnpj))"
    }
  }
]

Explanation

The [ ] characters in the split function indicate that the parameter should be interpreted as a regular expression. Their use is optional, but extremely useful when you want to split a string based on multiple characters or patterns.

In the CPF example, using "[.-]" ensures that the split happens for every occurrence of "." or "-" in the string.

If we removed the brackets — for example: "=split('.-',(@1,cpf))" — JOLT would look for the exact sequence ".-", which does not appear in the CPF value. As a result, the split wouldn't work. The same principle applies to the CNPJ example.

After splitting the values, we use the join function to reassemble the segments into a single string without formatting.

Eliminating duplicate values

This example shows how to deduplicate items inside a list based on a repeating field (id).

Input JSON

{
  "products": [
    {
      "id": 1
    },
    {
      "id": 2
    },
    {
      "id": 1
    }
  ]
}

Desired output JSON

{
  "products": [
    {
      "id": "1"
    },
    {
      "id": "2"
    }
  ]
}

Transformation spec

[
  {
    "operation": "shift",
    "spec": {
      "products": {
        "*": {
          "id": {
            "*": "ids.&[]"
          }
        }
      }
    }
  },
  {
    "operation": "shift",
    "spec": {
      "ids": {
        "*": {
          "$": "products[].id"
        }
      }
    }
  }
]

Explanation

In the first shift operation, the expression *: ids.&[] does two things:

• First, it selects all values from the id fields.

• Then, it uses each value as a field name in the output (&), ensuring that every repeated ID becomes a unique field.

• Finally, it places all these dynamically created fields into a new ids list.

In the second shift operation, the expression $: products[].id takes the name of each field generated inside the ids list and uses it as the value for the new id fields inside the products list.

Adding numeric values

This transformation calculates the total sum of values contained in a list of objects.

Input JSON

{
  "products": [
    {
      "id": 1,
      "name": "Product A",
      "value": 10
    },
    {
      "id": 2,
      "name": "Product B",
      "value": 20
    }
  ]
}

Desired output JSON

{
  "products": [
    {
      "id": 1,
      "name": "Product A",
      "value": 10
    },
    {
      "id": 2,
      "name": "Product B",
      "value": 20
    }
  ],
  "totalValue": 30
}

Transformation spec

[
  {
    "operation": "shift",
    "spec": {
      "products": {
        "*": {
          "*": "products[#2].&",
          "value": ["products[#2].&", "values[]"]
        }
      }
    }
  },
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "totalValue": "=doubleSum(@(1,valores))"
    }
  }
]

Explanation

Using the shift operation, we first create a values list containing all values from the products arrays while preserving the entire products structure at the end of the transformation.

Next, we apply the doubleSum function directly to the values list, allowing JOLT to sum all values dynamically.

This approach is especially useful when working with arrays, since JOLT’s arithmetic functions let you process all items in a list at once.

For simpler transformations, you can also apply functions explicitly, for example:

"=doubleSum(@(1,firstValue),@(1,secondValue))"

Multiplying two numeric values

Since JOLT has no multiplication function, this example performs equivalent logic using division.

Input JSON

{  
    "value1": 10,  
    "value2": 2
}

Desired output JSON

{  
    "value1": 10,  
    "value2": 2,  
    "inverseValue": 0.5,  
    "finalValue": 20
}

Transformation spec

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "inverseValue": "=divide(1, @(1,value2))",
      "finalValue": "=divideAndRound(2, @(1,value1), @(1,inverseValue))"
    }
  }
]

Explanation

By using this transformation, the goal is to simulate a multiplication in reverse. To do this, we:

• First divide one of the values by 1.

• Then divide the other value by the result of that first division.

This approach is required because the =divide and =divideAndRound functions only accept two parameters, meaning they cannot directly process more than two values at once.

Applying a filter based on field content

This example filters list elements by matching a substring inside the email field.

Input JSON

{
  "clients": [
    {
      "name": "Aquiles",
      "email": "[email protected]"
    },
    {
      "name": "Marcos",
      "email": "[email protected]"
    },
    {
      "name": "Yuri",
      "email": "[email protected]"
    }
  ]
}

Desired output JSON

{
  "clients": [
    {
      "name": "Aquiles",
      "email": "[email protected]"
    },
    {
      "name": "Yuri",
      "email": "[email protected]"
    }
  ]
}

Transformation spec

[
  {
    "operation": "shift",
    "spec": {
      "clients": {
        "*": {
          "email": {
            "*\\@gmail.com": {
              "@2": "gmail[]"
            }
          }
        }
      }
    }
  }
]

Explanation

In "*\\@gmail.com", we filter the value of the email field to return only the addresses that end with "gmail.com".

• The wildcard * captures any content before "@gmail.com".

• The sequence "\@" is required because the "@" symbol must be treated as a literal character, not as JOLT’s wildcard @.

• At the end of the expression, the "\\" is used to escape the backslash itself, ensuring it is interpreted correctly.

Including default values in a list

This transformation inserts a default field into each element of a list.

Input JSON

{
  "list": [
    { "a": "a", "b": "b" },
    { "c": "c", "d": "d" }
  ]
}

Desired output JSON

{
  "list": [
    { "a": "a", "b": "b", "e": "e" },
    { "c": "c", "d": "d", "e": "e" }
  ]
}

Transformation spec

Option 1 — default

[
  {
    "operation": "default",
    "spec": {
      "list[]": {
        "*": {
          "e": "e"
        }
      }
    }
  }
]

Option 2 — modify-default-beta

[
  {
    "operation": "modify-default-beta",
    "spec": {
      "list": {
        "*": {
          "e": "e"
        }
      }
    }
  }
]

Explanation

• default applies values when the field does not exist. Using list[] ensures the rule applies to each array entry.

• modify-default-beta behaves similarly to default, but it does not require the array notation ([]). When you specify "list": { "*": { ... } }, the operation automatically iterates over each element of the array.

Adding values to list elements

Adding a fixed value

This transformation adds the same fixed value to every element of a list.

You can choose how the value should behave:

• modify-overwrite-beta: Always sets the value, even if the field already exists.

• modify-default-beta: Sets the value only if the field does not already exist.

Input JSON

{
  "happy": "true",
  "statistics": [
    {
      "id": "A",
      "min": "2.0",
      "max": "10.0",
      "avg": "7.9"
    },
    {
      "min": "6",
      "max": "6",
      "avg": "6"
    },
    {
      "id": "C"
    }
  ]
}

Desired output JSON

{
  "happy": "true",
  "statistics": [
    {
      "id": "A",
      "min": "2.0",
      "max": "10.0",
      "avg": "7.9",
      "newValue": "test123"
    },
    {
      "min": "6",
      "max": "6",
      "avg": "6",
      "newValue": "test123"
    },
    {
      "id": "C",
      "newValue": "test123"
    }
  ]
}

Transformation spec

[
  {
    "operation": "modify-overwrite-beta",
    // To add the value only if it does not exist, change the operation to "modify-default-beta"
    "spec": {
      "statistics": {
        "*": {
          "newValue": "test123"
        }
      }
    }
  }
]

Adding dynamic values

In this scenario, each list element receives a value retrieved dynamically from another location in the JSON.

The syntax "@(n,path)" means: go up n levels from the current location and then follow the path to find the value.

Input JSON

{
  "levelA": {
    "levelB": {
      "happy": "true"
    }
  },
  "levelX": {
    "statistics": [
      {
        "id": "A",
        "min": "2.0",
        "max": "10.0",
        "avg": "7.9"
      },
      {
        "min": "6",
        "max": "6",
        "avg": "6"
      },
      {
        "id": "C"
      }
    ]
  }
}

Transformation

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "nivelX": {
        "statistics": {
          // "*" = each list element (also counts as a level)
          "*": {
            "newValue": "@(5,levelA.levelB.happy)"
          }
        }
      }
    }
  }
]

Explanation

• "*" iterates over every element in the statistics list.

• "@(5,levelA.levelB.happy)" climbs five levels up (each "*" also counts as a level), reaching the root.

• From there, the transformation reads the value of levelA.levelB.happy.

• Each list element receives that dynamic value.

Formatting dates using split and concat

This example demonstrates how to reformat a date by splitting it into parts and then concatenating the reordered values.

The transformation uses split to break the string into an array and concat to rebuild the date in the desired format (YYYYMMDD).

Input JSON

{  
  "data": {    
    "DATE": "18/09/1974"  
  }
}

Desired output JSON

{  
  "DATE": "19740918"
}

Transformation spec

[
  {
    "operation": "modify-overwrite-beta",
    "spec": {
      "data": {
        "array_aux": "=split('/',@(1,DATE))",
        "DATE": "=concat(@(1,array_aux[2]),@(1,array_aux[1]),@(1,array_aux[0]))"
      }
    }
  },
  {
    "operation": "shift",
    "spec": {
      "data": {
        "DATE": "&"
      }
    }
  }
]

Explanation

How the formatting works

• We use the modify-overwrite-beta operation to update the JSON content.

• The split function breaks the original date (18/09/1974) into an array: ["18", "09", "1974"]. It uses the "/" character as the delimiter.

• After splitting, the concat function reorders the array items to form the final date: year + month + day → "1974" + "09" + "18".

The split function can also receive regular expressions as parameters. For more examples, refer to: Split Functions tests on GitHub.

• In the final shift, we move the transformed DATE field to the root of the output JSON.

Applying simple IF-ELSE logic

When transforming data between systems, it's common to need a field that doesn't have a direct match in the source JSON. In many cases, you can derive this value using a simple IF-ELSE condition inside a JOLT transformation.

This example shows how to determine a client’s citizenship based on their country.

Input JSON

{ 
  "client": {   
    "name": "Sample client",   
    "age": "32",   
    "maritalStatus": "Single",   
    "country": "Brazil" 
  }
}

Desired output JSON

{
  "client": {
    "name": "Sample client",
    "citizenship": "Brazilian"
  }
}

Transformation spec

[
  {
    "operation": "shift",
    "spec": {
      "client": {
        "name": "client.name",
        "country": {
          "Brazil": {
            "#Brazilian": "client.citizenship"
          },
          "*": {
            "#Foreigner": "client.citizenship"
          }
        }
      }
    }
  }
]

Explanation

• The "country" field is evaluated using JOLT’s pattern-matching structure:

  • If the value is "Brazil", the literal Brazilian is assigned to client.citizenship.

  • For any other value (* wildcard), the literal Foreigner is used.

• The # operator creates a constant value during the transformation.

• The result is a clean JSON containing only the required fields: name and the derived citizenship.

Final considerations

With the concepts and examples covered in this guide, you now have a solid foundation to build powerful JOLT transformations, from simple restructuring to more advanced data manipulation for integration scenarios.

If you want to keep learning, we offer two great resources to support you:

• Digibee Academy: Transformer JOLT – Fundamentals: A structured learning path where you can dive deeper into the operations and operators.

• AI Assistant for Connectors: Your built-in helper for creating and adjusting JOLT specs directly while building pipelines.

These tools complement your knowledge and make it even easier to design transformations that are correct, efficient, and ready for production.