JSON-B Tutorial – Convert Java objects from and to JSON

Last Updated:  May 13, 2020 | Published: September 22, 2019

JSON is the current de-facto data format standard for exposing data via APIs. The Java ecosystem offers a bunch of libraries to create JSON from Java objects and vice-versa (GSON, Jackson, etc.). With the release of Java EE 8 and the JSR-367, we now have a standardized approach for this: JSON-B. With the transition of Java EE to the Eclipse Foundation, this specification is now renamed to Jakarta JSON Binding (JSON-B). In addition, this spec is also part of the Eclipse MicroProfile project.

Learn more about the JSON Binding (JSON-B) specification, its annotations, and how to use it in this blog post.

Specification profile: JSON Binding (JSON-B)

  • Current version: 1.0
  • GitHub repository
  • Specification homepage
  • Basic use case: Convert Java objects from and to JSON

Map objects from and to JSON

The central use case for JSON-B is mapping Java objects to and from JSON strings. To provide you an example, I'm using the following POJO:

Mapping Java objects and JSON messages requires an instance of the Jsonb. The specification defines a builder to create such an object. This instance can then be used for both mapping Java objects from and to JSON:

With no further configuration or adjustments, the JSON result contains all Java member variables (ignoring null values) as attributes in camel case.

Furthermore, you can also map a collection of Java objects to and from JSON arrays in a type-safe manner:

Configure the mapping of attributes

Sometimes the default mapping strategy of JSON-B might not fit your requirements and you want to e.g. customize the JSON attribute name or the date/number format. The specification offers a set of annotations to override the default mapping behavior, which can be applied to your Java POJO class.

With @JsonbProperty you can adjust the name of the JSON attribute name. If you use this annotation on a field level, it will affect both serialization and deserialization. On getter methods it affects only serialization and on setters only deserialization back to Java objects:

Next, you can use @JsonbTransient to avoid the serialization of a specific attribute to JSON at all:

If you plan to override the default behavior to not include null values to the JSON message, @JsonbNillable offers a way to do this. This annotation can only be used on class level and will affect all attributes:

For those use cases where you just want one attribute to be serialized to null, you can use @JsonbProperty(nillable=true) on fields/getters/setters.

In addition, you are able to adjust the format of dates and numbers with @JsonbDateFormat and @JsonbNumberFormat and specify your custom format:

Above all, if you don't want JSON-B to use the default no-arg constructor to deserialize JSON to Java objects, you can specify a custom constructor and use the annotation @JsonbCreator:

Make sure you use this annotation only once per class.

Define metadata for mapping JSON objects

Applying e.g. the @JsonbDateFormat to all your POJOs so they are all compliant to your custom date format, might be cumbersome and error-prone. Furthermore, if you use the annotations above to customize the mapping, you are not able to provide multiple representations if different clients require their own.

You can solve such requirements with a JsonbConfig instance and define global metadata for the mapping. Together with this configuration class, you can create a configured Jsonb instance and apply the mapping rules to all mappings of this instance:

Using this JsonbConfig, you are also able to configure things you can't with the annotations of the previous chapter: pretty-printing, locale information, naming strategies, ordering of attributes, encoding information, binary data strategies, etc. Have a look at the official user guide for all configuration attributes.

Provide a custom JSON-B mapping strategy

If all of the above solutions don't meet your requirements for mapping Java objects to and from JSON, you can implement your own JsonAdpater and get full access to serialization and deserialization:

With this adapter, you have full access to manage your JSON representation and to the deserialization logic. In this example, I'm using both the title and author for the final book title and concatenate both. Keep in mind that with a custom adapter, your JSON-B annotations on your POJO are overruled.

To make use of this JsonAdapter, you have to register it using a custom JsonbConfig:

If you need more low-level access to the serialization and deserialization, have a look at the JsonbSerializer and JsonbDeserializer interface (an example can be found in the official user guide).

YouTube video for using JSON-B 1.0

Watch the following YouTube video of my Getting started with Eclipse MicroProfile series to see JSON-B 1.0 in action:

You can find the source code with further instructions to run this example on GitHub. If you are looking for a solution to process JSON data, have a look at JSON-P.

Have fun using JSON-B,

Phil

>