Java JSON Tutorial

Java JSON APIs
    Jackson
    GSON
    Boon
    JSON.org
    JSONP
Implementing Your Own JSON Parser
Work in Progress

Jakob Jenkov
Last update: 2016-02-23

JSON is short for JavaScript Object Notation. JSON is a popular data exchange format between browsers and web servers because the browsers can parse JSON into JavaScript objects natively. On the server, however, JSON needs to be parsed and generated using JSON APIs. This Java JSON tutorial focuses on the various choices you have for parsing and generating JSON in Java.

This Java JSON tutorial consists of many pages. Each page describes a different aspect of e.g. a Java JSON API, or of working with JSON in Java in general. This page is only the frontpage / first page of this Java JSON tutorial. See the left menu for a list of all pages in this Java JSON tutorial.
Java JSON APIs

When JSON first became popular Java did not have a standard JSON parser / generator implementation. Instead Java developers had to rely on open source Java JSON APIs. Since then Java has attempted to address the missing Java JSON API in JSR 353. Keep in mind that JSR 353 is not yet an official standard (as I am writing this).

The Java community has also developed several open source Java JSON APIs. The open source Java JSON APIs often offer more choice and flexibility in how you can work with JSON than the JSR 353 API. Therefore the open source APIs are still decent options. Some of the more well-known open source Java JSON APIs are:

Jackson
GSON
Boon
JSON.org

If you prefer to use a JSR 353 compliant JSON parser you can use JSONP.

Both the open source and JSONP Java JSON APIs will be covered in a bit more detail in the following sections.
Jackson

Jackson is a Java JSON API which provides several different ways to work with JSON. Jackson is one of the most popular Java JSON APIs out there. You can find Jackson here:

https://github.com/FasterXML/jackson

Jackson contains 2 different JSON parsers:

The Jackson ObjectMapper which parses JSON into custom Java objects, or into a Jackson specific tree structure (tree model).
The Jackson JsonParser which is Jackson's JSON pull parser, parsing JSON one token at a time.

Jackson also contains two JSON generators:

The Jackson ObjectMapper which can generate JSON from custom Java objects, or from a Jackson specific tree structure (tree model).
The Jackson JsonGenerator which can generate JSON one token at a time.

GSON

GSON is a Java JSON API from Google. That is where the G in GSON comes from. GSON is reasonably flexible, but the last time I saw a benchmark, Jackson was faster than GSON. Which you choose to use is up to you. You can find GSON here:

https://github.com/google/gson

GSON contains 3 Java JSON parsers:

The Gson class which can parse JSON into custom Java objects.
The GSON JsonReader which is GSON's pull JSON parser - parsing JSON one token at a time.
The GSON JsonParser which can parse JSON into a tree structure of GSON specific Java objects.

GSON also contains a JSON generator:

The Gson class which can generate JSON from custom Java classes.

Boon

Boon is a less known Java JSON API, but it is supposedly the fastest of them all (according to the last benchmark I saw). Boon is being used as the standard JSON API in Groovy. You can find Boon here:

https://github.com/boonproject/boon

Boon’s API is very similar to Jackson’s (so it is easy to switch).But - Boon is more than just a Java JSON API. Boon is a general purpose toolkit for working with data easily. This is handy e.g. inside REST services, file processing apps etc.

Boon contains the following Java JSON parsers:

The Boon ObjectMapper which can parse JSON into custom objects or Java Maps

Like in Jackson, the Boon ObjectMapper can also be used to generate JSON from custom Java objects.
JSON.org

JSON.org also has an open source Java JSON API. This was one of the first Java JSON APIs available out there. It is reasonably easy to use, but not as flexible or fast as the other JSON APIs mentioned above. You can find JSON.org here:

https://github.com/douglascrockford/JSON-java

As the Github repository also says - this is an old Java JSON API. Don’t use it unless your project is already using it. Otherwise, look for one of the other, more up-to-date options.
JSONP

JSONP is a JSR 353 compliant JSON API for Java. Being JSR 353 compliant means, that if you use the standard APIs it should be possible to exchange the JSONP implementation with another API in the future, without breaking your code. You can find JSONP here:

https://jsonp.java.net/

I would also expect some Java application server vendors to provide JSR 353 compliant JSON APIs in the future (if not already).
Implementing Your Own JSON Parser

There might be some situations where you need or want to implement your own JSON parser in Java. For instance if you need certain features the standard JSON APIs don’t have, or if you need a bare bones API that is very small etc.

Whatever the reason, if you are interested in implementing your own JSON parser, I have published a longer article on how to design a JSON parser on InfoQ.com:

http://www.infoq.com/articles/HIgh-Performance-Parsers-in-Java-V2
Work in Progress

This Java JSON tutorial is work in progress, like all my tutorials. As I learn more about processing JSON in Java, I will update this Java JSON tutorial. If something is missing, either be patient and wait for it to be added, or send me an email. You can find an email address on my about page.
Next: Jackson Installation
Tweet

Jakob Jenkov