Java JOLT library tutorial with Examples

1. What is JOLT?

JOLT (JSON-to-JSON Transformation) is an open-source Java library (originally from Bazel/Spotify) used to:

✔ Transform JSON into a different JSON
✔ Restructure fields
✔ Rename keys
✔ Change nesting
✔ Flatten or unflatten
✔ Filter fields
✔ Dynamically map values
✔ Build complex transformation pipelines

JOLT uses a transformation spec, written as JSON, to tell how input JSON should be transformed.

---

2. Why and When to Use JOLT?

Use JOLT when:

Your application needs to convert JSON from one format to another

Examples:

• Backend receives API JSON and needs to convert it to another JSON format.
• Integrating with 3rd-party APIs that return weird JSON structure.

You don’t want to write manual JSON parsing/conversion

Without JOLT you'd write dozens of lines of ObjectMapper, maps, loops, etc.

JOLT reduces this to a tiny JSON transformation spec.

You want data transformation configurable — not hardcoded

You can store the spec in:

• a file,
• a database,
• config properties,
• or generate dynamically.

---

3. What is a Spec?

A spec is a JSON array describing transformation steps.

Example:

[
  {
    "operation": "shift",
    "spec": {
      "user": {
        "name": "username"
      }
    }
  }
]

This means:

user.name  →  username

---

4. JOLT Operations

Operation	Purpose
shift	Move fields from input to output (mapping).
default	Add missing fields with default values.
remove	Remove fields.
sort	Sort JSON keys.
cardinality	Force single-item arrays or multi-item arrays.
modify-overwrite-beta	Modify values (math, string concat, etc.).
modify-default-beta	Modify or add default values.

Most commonly used = shift.

---

5. Using Spec from File, String, Java Object

A) Spec from .json file

List<Object> specs = JsonUtils.filepathToList("spec.json");
Chainr chainr = Chainr.fromSpec(specs);
Object output = chainr.transform(inputJson);

B) Spec from JSON String

String specJson = "[ { \"operation\": \"shift\", \"spec\": {\"a\":\"b\"} } ]";
List<Object> specs = JsonUtils.jsonToList(specJson);
Chainr chainr = Chainr.fromSpec(specs);

C) Spec as Java object

List<Object> specs = new ArrayList<>();

Map<String, Object> shiftOp = new HashMap<>();
shiftOp.put("operation", "shift");

Map<String, Object> shiftSpec = new HashMap<>();
shiftSpec.put("a", "b");

shiftOp.put("spec", shiftSpec);

specs.add(shiftOp);

Chainr chainr = Chainr.fromSpec(specs);

---

6. Explanation of JOLT Symbols (@, $, &)

These symbols are used inside shift mapping.

---

@ → Value reference

Points to value of current key.

Input:

{ "name": "John" }

Spec:

{
  "name": "personName.@"
}

Output:

{
  "personName": "John"
}

---

$ → Key reference

Refers to the current key name.

Input:

{ "a": 10, "b": 20 }

Spec:

"*": "result.&"

Output:

{
  "result": {
    "a": 10,
    "b": 20
  }
}

---

& → Copy matched key name

Similar to $ but used inside array indexing or deep nesting.

Input:

{ "items": { "101": "Book", "102": "Pen" } }

Spec:

{
  "items": {
    "*": "products.&"
  }
}

Output:

{
  "products": {
    "101": "Book",
    "102": "Pen"
  }
}

---

7. Working With JSON Objects and Arrays

Example input with arrays

{
  "users": [
    { "id": 1, "name": "A" },
    { "id": 2, "name": "B" }
  ]
}

Spec: convert list → map by id

[
  {
    "operation": "shift",
    "spec": {
      "users": {
        "*": {
          "@": "usersById.@(1,id)"
        }
      }
    }
  }
]

Explanation:

• * → for each array element
• @ → copy object
• @(1,id) → go 1 level up (the object) and fetch id field → use it as key

Output:

{
  "usersById": {
    "1": { "id": 1, "name": "A" },
    "2": { "id": 2, "name": "B" }
  }
}

---

8. Full Implementation in Java (Real Example)

Maven dependency

<dependency>
  <groupId>com.bazaarvoice.jolt</groupId>
  <artifactId>jolt-core</artifactId>
  <version>0.1.8</version>
</dependency>

<dependency>
  <groupId>com.bazaarvoice.jolt</groupId>
  <artifactId>json-utils</artifactId>
  <version>0.1.8</version>
</dependency>

---

Example Input JSON

{
  "user": {
    "id": 10,
    "first": "John",
    "last": "Doe"
  }
}

---

Spec Example (shift + default + remove)

spec.json:

[
  {
    "operation": "shift",
    "spec": {
      "user": {
        "id": "id",
        "first": "name.first",
        "last": "name.last"
      }
    }
  },
  {
    "operation": "default",
    "spec": {
      "role": "USER"
    }
  },
  {
    "operation": "remove",
    "spec": {
      "unusedField": ""
    }
  }
]

---

Java Code

import com.bazaarvoice.jolt.Chainr;
import com.bazaarvoice.jolt.JsonUtils;

import java.util.List;
import java.util.Map;

public class JoltExample {

    public static void main(String[] args) {

        // 1. Load input JSON
        Map<String, Object> input = JsonUtils.jsonToMap(
                "{ \"user\": {\"id\":10, \"first\":\"John\", \"last\":\"Doe\"} }"
        );

        // 2. Load spec from file
        List<Object> specs = JsonUtils.filepathToList("spec.json");

        // 3. Create transformer
        Chainr chainr = Chainr.fromSpec(specs);

        // 4. Transform JSON
        Object output = chainr.transform(input);

        // 5. Print output
        System.out.println(JsonUtils.toJsonString(output));
    }
}

---

Output

{
  "id": 10,
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "role": "USER"
}

---

Summary (Cheat Sheet)

Topic	Summary
What is JOLT	JSON transformer library for Java
Why use it	Easy JSON-to-JSON mapping without writing code
Spec	JSON instructions for transformation
Operations	shift, default, remove, modify, sort, cardinality
Symbols	@ value, $ key, & copy name
From file/string/object	Supported
Arrays	Wildcards + operators like @(1,id)
Java Implementation	Use Chainr and JsonUtils