Skip to content
A framework for working with json in Java the "proper" way.
Java Shell
Find file
Pull request Compare This branch is 2 commits ahead, 451 commits behind jillesvangurp:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Getting started



JsonJ is a framework for working with json in Java the “proper” way. No mappings or model classes, it’s all just lovely json, but in Java.

JsonJ is optimized for working with json in a programmatic way rather than in a reflective/annotated domain object way. This means a json array is represented as a java.util.List, a dictionary is represented as a java.util.Map, etc.

Just think about it, the whole point of json is a straightforward serialization and deserialization of simple, native data structures consisting of primitives, lists and dictionaries that you will find in a lot of languages other than Java. In Java things are slightly more complicated because lists and dictionaries are mere classes rather than native types. This means for example that you have to deal with generics; you may want to pick alternate implementations of the Map interface or skip that altogether and instead use a completely different framework. For that reason, dealing with json in Java is a lot less straightforward than it would be in for example Ruby, Python, or Javascript.

The purpose of the JsonJ framework is to remove these barriers and allow you to write code that has a low amount of verbosity. I can’t change the language but I can bend the rules a little when it comes to maps and lists. The JsonJ framework simply extends LinkedHashMap and LinkedList to provide default implementations of json dictionaries and lists that implement APIs any java developer will be familiar with. Additionally, some convenience methods have been added to these classes to give you sensible hashcode and equals implementations, a deepClone method, as well as methods for manipulating the contents of the dictionary and list structures. Finally, a builder class is provided and of course the framework would not be complete without a good parser and pretty printing serializer.


  • 0.9 fix several serialization bugs, array.addAll and the builder now play nice with collections, toString now serializes proper json (beware with using JsonPrimitive.toString() on json strings: they now include quotes!; use asString() instead).
  • 0.8 fix escaping, npe fix John Goodwin merged, misc minor fixes
  • 0.7 Add support for converting a json element to a dom tree so that things like xpath or xsl can be used on it
  • 0.6 Support for deepCloning, object sorting added. Use String.intern() on object keys to optimize frequent operations on json objects.
  • 0.5 Serializer and parser now properly escape and unescape string literals.
  • 0.4 Bug fixes, changed groupid, documentation.
  • 0.3 Several new methods added in JsonArray and JsonObject; fixed the parser bug where nested arrays and objects were not handled correctly.
  • 0.2 Several bug fixes
  • 0.1 First release

What’s with the name

It’s pronounced json-j, or jasonjay. It doesn’t mean anything in particular other than “json for java”, or something. Well, trying to come up with a name that is not already used is quite a challenge and I wanted to stuff the acronym json in there, keep it short, and not have the first hit on Google be something else than this. So, JsonJ it is.

Why another framework?

There are many frameworks for handling Json in java. So why create another one? From my point of view these frameworks are all flawed in one or more of the following ways:

  1. they assume the user has model classes that need to be serialized and deserialized to and from java
  2. they use an internal representation of the various json types that is not very friendly to work with if you want to manipulate them directly
  3. they don’t treat json as a first class entity and merely try to hide the fact that your data is stored as json
  4. they don’t use the Java collections framework
  5. they use final classes, so your options to work around any limitations are a bit limited.

Don’t get me wrong, some of these frameworks are excellent. And some of these frameworks are quite usable even if you do use them the way I want to use them.

However, from having used one of them extensively (GSon), I have learned that there is room for improvement. Since we’re talking the type of improvement that is likely backwards compatibility breaking (i.e. not very likely to be implemented in one of the existing frameworks), I went ahead and created my solution.

For who is this framework intended

Anyone who plans to write a lot of business logic in Java that manipulates json data structures and who doesn’t wish to write model classes in Java to hide the fact that json is being used. If you are like me, you feel somewhat stuck having to deal with awkward json frameworks while all the cool Ruby,Python, and Javascript kids get to use a serialization that is natively supported in their language. This framework is for you.

Jsonj had a bit of a rocky start where especially the early versions had loads of bugs. I’ve basically ran into most of them and have been using it in a few projects. Most recent development has been about addressing very minor issues and adding new features. As of 0.8 it seems to work for most of what I do with it and I’m not aware of major open issues. I’ve processed many gigabytes of information with it and am fairly confident to have caught all major issues at this point. So, I might cut a 1.0 fairly soon.

Which version should I use?

The latest release or snapshot typically. Beyond the version number, there is not much difference between a release and a snapshot. I don’t bother with the ceremony for each commit. Seriously, the older versions have bugs that I know about and already fixed. Why take the risk? The head of the repository should be fine. If you prefer non snapshot releases, go for the latest tag. The release process I use is “release frequently and don’t keep working stuff unreleased”. My QA process is verifying I did not break any tests (in combination with good test coverage).

I found a bug, what should I do

File a bug on this github project, or just mail/im me directly. Either way, if I agree something is broken, I will fix it. Alternatively, feel free to clone & own. That’s what github is all about.

How to build JsonJ

mvn clean install should do the trick with maven 3.x (and probably 2.x as well). I’m not a big maven fan but this is a relatively trivial project and it’s just easier this way.

Where is the documentation?

Look at the javadoc and the tests. Particularly this one here shows off most of the features this framework has.


The license is the MIT license, a.k.a. the expat license. The rationale for choosing this license is that I want to maximize your freedom to do whatever you want with the code while limiting my liability for the damage this code could potentially do. I do appreciate attribution but not enough to require it in the license (beyond the obligatory copyright notice).


  1. I’ve been greatly influenced by the classes representing the json primitives in the GSon framework. If only they implemented Map and List and weren’t final. But lovely framework and would use it again.
  2. I spend quite a bit of time figuring out a way of parsing Json that didn’t involve me generating a lot of source code with javacc, antlr or similar tools. Then I stumpled onto json-simple and wrote the parser for JsonJ in under two hours using a custom json-simple content handler. It seems to work and json-simple is pretty fast as well.
  3. This code is very loosely based on work I did at work with several colleagues. No code was copy pasted but I definitely took some ideas and improved on them. You know who you are. Thanks.
Something went wrong with that request. Please try again.