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
✔ …


This content originally appeared on DEV Community and was authored by sadiul hakim

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


This content originally appeared on DEV Community and was authored by sadiul hakim


Print Share Comment Cite Upload Translate Updates
APA

sadiul hakim | Sciencx (2025-11-22T09:20:26+00:00) Java JOLT library tutorial with Examples. Retrieved from https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/

MLA
" » Java JOLT library tutorial with Examples." sadiul hakim | Sciencx - Saturday November 22, 2025, https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/
HARVARD
sadiul hakim | Sciencx Saturday November 22, 2025 » Java JOLT library tutorial with Examples., viewed ,<https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/>
VANCOUVER
sadiul hakim | Sciencx - » Java JOLT library tutorial with Examples. [Internet]. [Accessed ]. Available from: https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/
CHICAGO
" » Java JOLT library tutorial with Examples." sadiul hakim | Sciencx - Accessed . https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/
IEEE
" » Java JOLT library tutorial with Examples." sadiul hakim | Sciencx [Online]. Available: https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/. [Accessed: ]
rf:citation
» Java JOLT library tutorial with Examples | sadiul hakim | Sciencx | https://www.scien.cx/2025/11/22/java-jolt-library-tutorial-with-examples-2/ |

Please log in to upload a file.



There are no updates yet.
Click the Upload button above to add an update.

You must be logged in to translate posts. Please log in or register.

Related Posts