Jolt turns a JSON spec into a chain of structural transforms

Structure yes, values no, and the line is deliberate

Jolt exists because reshaping JSON in Java usually means either string juggling or an XSLT detour, and Bazaarvoice wanted the transform written down as data. The scope is narrow on purpose. The README says Jolt focuses on transforming the structure of your JSON data, not manipulating specific values, and gives the workflow it has in mind: use Jolt to get most of the structure right, then write code to fix values.

That single sentence explains most of what you will and will not like about the library. If your problem is that a nested document arrives with fields at the wrong depth, the wrong names, or the wrong cardinality, Jolt is aimed squarely at it. If your problem is computing a total, formatting a date or normalising a string, Jolt deliberately stays out of the way and you write Java.

The two situations the README names as useful are transforming JSON coming out of ElasticSearch, MongoDb or Cassandra before sending it to the world, and extracting data from large documents for your own consumption. Both are extraction and reshaping, not enrichment. The input and output are hydrated JSON, meaning in-memory trees of Maps, Lists and Strings, and Jackson, or whatever you prefer, does the serializing on both sides.

Five stock transforms, each with its own DSL

A Jolt chain is a list of transforms applied in order, and each transform has a narrow DSL so it can do one job well. The stock set is five.

shift copies data from the input tree into the output tree, and it is the one that does most of the work in a typical chain. default applies default values to the tree. remove deletes data. sort orders Map keys alphabetically, which the README frames as being for debugging and human readability rather than for output contracts. cardinality fixes the shape of collections: the README's example is a urls element that is usually a List but collapses to a String when there is exactly one entry.

cardinality is the one that causes trouble in practice, because a downstream consumer that expects an array now has to handle both shapes. It is also the transform that makes Jolt worth having, because that inconsistency is exactly what hand-written extraction code tends to paper over badly.

Every stock transform affects structure. To change a value you implement the Transform interface yourself and splice it into the chain. A class that implements Transform or ContextualTransform, optionally also SpecDriven, becomes a chain member, which is how a project extends Jolt without forking it.

Chainr is where a spec becomes a running transform

Running Jolt means constructing a Chainr with a list of transforms, and the spec for that list is itself JSON. The Java side is short:

Chainr chainr = JsonUtils.classpathToList( "/path/to/chainr/spec.json" );

Object input = elasticSearchHit.getSource(); // ElasticSearch already returns hydrated JSon

Object output = chainr.transform( input );

return output;

Two things in that snippet matter. The spec is read from the classpath through JsonUtils, so the transform definition is a resource file rather than a compiled literal, which is what makes it reviewable and swappable. And the input is whatever the source system already hydrated, since ElasticSearch already returns hydrated JSON.

The repository layout supports reading as documentation. jolt-core holds the transforms, json-utils holds Diffy, the comparison helper used in tests, cli/ is the command line entry, complete/ looks like an assembled distribution, guice/ suggests a Guice binding example, bin/ holds scripts, and parent/ and pom.xml carry the Maven build with parent/parent aggregator.

There is also a browser demo at jolt-demo.appspot.com where you can paste input JSON and a spec and see the result. The README is candid about it: the instance is free Google App Engine, so it may take a minute to spin up.

The unit test resources are the real tutorial

Jolt does not teach its DSL through a manual. The README points at the unit tests in jolt-core/src/test/resources/json/shiftr as the place to see the Shiftr DSL in action, describing them as nice bite sized transform examples, and directs you to read the Shiftr javadoc afterwards.

The learning method is worth copying even if you never use the library. Every fixture follows the same three-key shape:

{
    "input": {
        // sample input
    },

    "spec": {
        // transform spec
    },

    "expected": {
        // what the output of the transform looks like
    }
}

You read input and expected first, work out how the data moves, and only then look at the spec to see which construct facilitated it. That ordering is the opposite of how a reference manual teaches, and it is the reason the DSL is learnable at all: the spec is a diff against reality rather than a vocabulary to memorise.

The same pattern covers Chainr itself, with the spec example at jolt-core/src/test/resources/json/chainr/integration/firstSample.json. The first Shiftr test is at jolt-core/src/test/resources/json/shiftr/firstSample.json. Two files, both small, and they are the entire onboarding path.

Why Jolt was written instead of XSLT or a template

The README names the two alternatives it was built to avoid, and the reasoning is more useful than a feature list.

The first approach is JSON to XML to XSLT or STX, then back to JSON. Beyond being a Rube Goldberg route, the objection is that XSLT tries to do the entire transform with a single DSL, which the README argues is more complicated than Jolt's approach of several narrow transforms chained together.

The second approach is a template engine such as Velocity or FreeMarker that consumes hydrated JSON and writes textual JSON. Here the argument is about direction of travel: you end up working backwards from the output format to the input, and for anything non-trivial the template's structure is dictated by the output shape.

Jolt's answer to both is that a transform is a pipeline of small declarative steps over a tree, not a document template. The library also has a CLI in cli/ and a bin/ directory for running it outside a JVM application, which the README's table of contents lists under its own heading.

The demo being server-side is the one privacy wrinkle: it posts your JSON to a hosted instance. For production work you would run the chain in your own JVM, which is what the Java snippet shows.

What you will still have to write yourself

There are honest gaps, and they follow from the design rather than from immaturity.

Value manipulation is the big one, and it is not a missing feature so much as a boundary. Anything that reads a value and computes another value is Java code implementing Transform, which means a chain with several value steps has several classes, each needing its own spec entry.

Getting help is unstructured. The README says that if a transform is not working and you need help, to create an issue in Jolt, and to include the input and the desired output. There is no discussion forum or chat channel mentioned, so debugging help is asynchronous and tied to the repository.

Documentation lives in three places that you should treat as one: the README for scope and reasoning, the javadoc per transform (Shiftr, Defaultr, Removr, CardinalityTransform, Sortr), and a slide deck linked from the README covering motivation, development and transforms. None of them is a reference manual, and that is the honest characterisation.

On maintenance, the situation deserves a look before you depend on it. The last push was on 2026-09-23 and the repository is not archived, but the latest tagged release is jolt-0.1.6 from 2022-03-28, preceded by jolt-0.1.5 in 2021 and jolt-0.1.1 in 2018. Whatever has landed since then is on master without a tag. Continuous integration config is a.travis.yml file, which dates the build setup even though the code has moved since.

Editorial conclusion

Jolt earns a place when the shape of JSON from ElasticSearch, MongoDb or Cassandra has to change before it leaves your system and you want that change reviewable as data in a repository rather than as Java string concatenation. It is the wrong choice for value manipulation, since every stock transform affects structure only and each value fix costs a custom Transform implementation. Before adopting it, load one of the shiftr unit test resources in jolt-core/src/test/resources/json/shiftr and confirm that its input, spec and expected pattern matches how your team writes specs, and check the release situation first: the last tagged release was jolt-0.1.6 on 2022-03-28 while the last push was on 2026-09-23.

Frequently asked questions

Official sources

1. bazaarvoice/jolt on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases