Building basic JOLT transformations

Learn how each basic JOLT transformation (shift, default, remove, and sort) works.

JOLT can be used for diverse types of transformations, from basic to advanced. In this document, we will introduce you to the basic operations, that allows you to:

• Restructure the JSON or rename fields.

• Insert default values if fields are missing.

• Delete specific fields.

• Arrange fields in alphabetical order.

Tip: Test the examples from this document in the JOLT playground.

Understanding the basic JOLT operations

In this section, you’ll learn how each basic JOLT operation works (shift, default, remove, and sort) and when to use them.

shift

The shift operation restructures a JSON object by remapping its fields, without modifying their values. It works by specifying where to extract values from in the original JSON and where to place them in the new structure.

Practical example

• Use case: Transforming a product catalog to match a new format.

• Goal: Group product details under a details object and rename fields.

Input JSON

{
  "product": {
    "id": "12345",
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "price": 699.99,
    "currency": "USD",
    "stock": 25
  }
}

Desired output JSON

{
  "productId": "12345",
  "details": {
    "name": "Smartphone X1",
    "brand": "TechBrand",
    "pricing": {
      "amount": 699.99,
      "currency": "USD"
    },
    "availability": 25
  }
}

Transformation spec

[
  {
    "operation": "shift",
    "spec": {
      "product": {
        "id": "productId",
        "name": "details.name",
        "brand": "details.brand",
        "price": "details.pricing.amount",
        "currency": "details.pricing.currency",
        "stock": "details.availability"
      }
    }
  }
]

Explanation

• "id": "productId" moves the product.id to the top level with a new key.

• "name" and "brand" are grouped under details.

• "price" and "currency" are nested under details.pricing to organize pricing information.

• "stock" is renamed to availability and grouped under details.

Using dot notation (.) and hierarchical paths in the spec, you can organize complex output structures with minimal effort.

Only the fields explicitly mapped in the transformation spec will appear in the output. Any other data from the input is ignored.

default

The default operation adds fields to a JSON object when they don’t already exist. It’s useful for populating missing data with predefined values.

Practical example

• Use case: Completing customer data with a default birth date.

• Goal: Ensure that the output JSON includes the birthDate field, even if it’s missing in the output.

Input JSON

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123-45-6789"
 }
}

Desired output JSON

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123-45-6789",
   "birthDate": "01/01/1970"
 }
}

Transformation spec

[    
 {
   "operation": "default",
   "spec": {
     "customer": {
       "birthDate": "01/01/1970"
     }
   }
 }
]

Explanation

• The default operation checks whether the field customer.birthDate exists.

• If it’s missing, the value "01/01/1970" is added as a default.

• If the field already exists, its original value is preserved.

This operation is useful when you want to ensure that specific fields are present in the output, even if they’re not provided in the input.

The default operation does not overwrite existing values, it only fills missing values.

remove

The remove operation deletes specific fields or objects from a JSON structure. You must navigate to the field you want to remove and assign it an empty string (“ ”) in the spec.

Practical example

• Use case: Cleaning up customer data by removing unnecessary fields.

• Goal: Exclude the birthDate field from the customer object.

Input JSON

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123.456.789.10",
   "birthDate": "01/01/1970"
 }
}

Desired output JSON

{
 "customer": {
   "name": "Customer Default",
   "ssn": "123.456.789.10"
 }
}

Transformation spec

[
 {
   "operation": "remove",
   "spec": {
     "customer": {
       "birthDate": ""
     }
   }
 }
]

Explanation

• The transformation navigates to customer.birthDate and removes it by assigning "" (an empty string).

• Only fields explicitly assigned to an empty string will be removed.

• Any incorrect or non-empty assignment will cause the operation to fail.

Make sure to use an empty string (" ") to indicate that the field should be removed. This is required for the operation to succeed.

sort

The sort operation organizes all fields and objects in a JSON in alphabetical order by key name. It applies globally. The sort order can’t be customized, and only the keys are sorted, not the values.

Practical example

• Use case: Alphabetizing employee data fields for consistency.

• Goal: Ensure all fields in the output appear in alphabetical order.

Input JSON

{
 "employee": {
   "phone": "9 9999-9999",
   "name": "Employee Sort",
   "birthDate": "01/01/1980",
   "role": "JOLT Analyst"
 }
}

Desired output JSON

{
 "employee": {
   "birthDate": "01/01/1980",
   "name": "Employee Sort",
   "phone": "9 9999-9999",
   "role": "JOLT Analyst"
 }
}

Transformation spec

[
 {
   "operation": "sort"
 }
]

Explanation

• No spec is needed for the sort operation. Only the operation must be declared.

• All object fields in the JSON are sorted alphabetically by key name.

• Sorting applies recursively to nested objects as well.

Continue learning

Now that you’ve covered the essentials, you can move on to the next topics:

• JOLT operators, key elements that make your specifications more dynamic and flexible.

• Advanced operations, where you’ll explore more sophisticated transformation techniques.

• Use case examples, demonstrating how JOLT works in real integration scenarios.