Introduction to the JSON Binding API (JSR 367) in Java

1. Overview

For a long time, there was no standard for JSON processing in Java. The most common libraries used for JSON processing are Jackson and Gson.

Recently, Java EE7 came with an API for parsing and generating JSON (JSR 353: Java API for JSON Processing).

And finally, with the release of JEE 8, there is a standardized API (JSR 367: Java API for JSON Binding (JSON-B)).

For now, its main implementations are Eclipse Yasson (RI) and Apache Johnzon.

2. JSON-B API

2.1. Maven Dependency

Let’s start by adding the necessary dependency.

Keep in mind that in many cases it’ll be enough to include the dependency for the chosen implementation and the javax.json.bind-api will be included transitively:

<dependency>
    <groupId>javax.json.bind</groupId>
    <artifactId>javax.json.bind-api</artifactId>
    <version>1.0</version>
</dependency>

The most recent version can be found at Maven Central.

3. Using Eclipse Yasson

Eclipse Yasson is the official reference implementation of JSON Binding API (JSR-367).

3.1. Maven Dependency

To use it, we need to include the following dependencies in our Maven project:

<dependency>
    <groupId>org.eclipse</groupId>
    <artifactId>yasson</artifactId>
    <version>1.0.1</version>
</dependency>
<dependency>
    <groupId>org.glassfish</groupId>
    <artifactId>javax.json</artifactId>
    <version>1.1.2</version>
</dependency>

The most recent versions can be found at Maven Central.

4. Using Apache Johnzon

Another implementation we can use is Apache Johnzon which complies with the JSON-P (JSR-353) and JSON-B (JSR-367) APIs.

4.1. Maven Dependency

To use it, we need to include the following dependencies in our Maven project:

<dependency>
    <groupId>org.apache.geronimo.specs</groupId>
    <artifactId>geronimo-json_1.1_spec</artifactId>
    <version>1.0</version>
</dependency>
<dependency>
    <groupId>org.apache.johnzon</groupId>
    <artifactId>johnzon-jsonb</artifactId>
    <version>1.1.4</version>
</dependency>

The most recent versions can be found at Maven Central.

5. API Features

The API provides annotations for customizing serialization/deserialization.

Let’s create a simple class and see how the example configuration looks like:

public class Person {

    private int id;

    @JsonbProperty("person-name")
    private String name;
    
    @JsonbProperty(nillable = true)
    private String email;
    
    @JsonbTransient
    private int age;
     
    @JsonbDateFormat("dd-MM-yyyy")
    private LocalDate registeredDate;
    
    private BigDecimal salary;
    
    @JsonbNumberFormat(locale = "en_US", value = "#0.0")
    public BigDecimal getSalary() {
        return salary;
    }
 
    // standard getters and setters
}

After serialization, an object of this class will look like:

{
   "email":"jhon@test.com",
   "id":1,
   "person-name":"Jhon",
   "registeredDate":"07-09-2019",
   "salary":"1000.0"
}

The annotations used here are:

• @JsonbProperty – which is used for specifying a custom field name
• @JsonbTransient – when we want to ignore the field during deserialization/serialization
• @JsonbDateFormat – when we want to define the display format of the date
• @JsonbNumberFormat – for specifying the display format for numeric values
• @JsonbNillable – for enabling serialization of null values

5.1. Serialization and Deserialization

First of all, to obtain the JSON representation of our object, we need to use the JsonbBuilder class and its toJson() method.

To start, let’s create a simple Person object like this:

Person person = new Person(
  1, 
  "Jhon", 
  "jhon@test.com", 
  20, 
  LocalDate.of(2019, 9, 7), 
  BigDecimal.valueOf(1000));

And, instantiate the Jsonb class:

Jsonb jsonb = JsonbBuilder.create();

Then, we use the toJson method:

String jsonPerson = jsonb.toJson(person);

To obtain the following JSON representation:

{
    "email":"jhon@test.com",
    "id":1,
    "person-name":"Jhon",
    "registeredDate":"07-09-2019",
    "salary":"1000.0"
}

If we want to do the conversion the other way, we can use the fromJson method:

Person person = jsonb.fromJson(jsonPerson, Person.class);

Naturally, we can also process collections:

List<Person> personList = Arrays.asList(...);
String jsonArrayPerson = jsonb.toJson(personList);

To obtain the following JSON representation:

[ 
    {
      "email":"jhon@test.com",
      "id":1,
      "person-name":"Jhon", 
      "registeredDate":"09-09-2019",
      "salary":"1000.0"
    },
    {
      "email":"jhon1@test.com",
      "id":2,
      "person-name":"Jhon",
      "registeredDate":"09-09-2019",
      "salary":"1500.0"
    },
    ...
]

To convert from JSON array to List we’ll use the fromJson API:

List<Person> personList = jsonb.fromJson(
  personJsonArray, 
  new ArrayList<Person>(){}.getClass().getGenericSuperclass()
);

5.2. Custom Mapping with JsonbConfig

The JsonbConfig class allows us to customize the mapping process for all classes.

For example, we can change the default naming strategies or the properties order.

Now, we’ll use the LOWER_CASE_WITH_UNDERSCORES strategy:

JsonbConfig config = new JsonbConfig().withPropertyNamingStrategy(
  PropertyNamingStrategy.LOWER_CASE_WITH_UNDERSCORES);
Jsonb jsonb = JsonbBuilder.create(config);
String jsonPerson = jsonb.toJson(person);

To obtain the following JSON representation:

{
   "email":"jhon@test.com",
   "id":1,
   "person-name":"Jhon",
   "registered_date":"07-09-2019",
   "salary":"1000.0"
}

Now, we’ll change the property order with the REVERSE strategy. Using this strategy, the order of properties is in reverse order to lexicographical order.
This can also be configured at compile time with the annotation @JsonbPropertyOrder. Let’s see it in action:

JsonbConfig config 
  = new JsonbConfig().withPropertyOrderStrategy(PropertyOrderStrategy.REVERSE);
Jsonb jsonb = JsonbBuilder.create(config);
String jsonPerson = jsonb.toJson(person);

To obtain the following JSON representation:

{
    "salary":"1000.0",
    "registeredDate":"07-09-2019",
    "person-name":"Jhon",
    "id":1,
    "email":"jhon@test.com"
}

5.3. Custom Mapping with Adapters

When the annotations and the JsonbConfig class aren’t enough for us, we can use adapters.

To use them, we’ll need to implement the JsonbAdapter interface, which defines the following methods:

• adaptToJson – With this method, we can use custom conversion logic for the serialization process.
• adaptFromJson – This method allows us to use custom conversion logic for the deserialization process.

Let’s create a PersonAdapter to process the id and name attributes of the Person class:

public class PersonAdapter implements JsonbAdapter<Person, JsonObject> {

    @Override
    public JsonObject adaptToJson(Person p) throws Exception {
        return Json.createObjectBuilder()
          .add("id", p.getId())
          .add("name", p.getName())
          .build();
    }

    @Override
    public Person adaptFromJson(JsonObject adapted) throws Exception {
        Person person = new Person();
        person.setId(adapted.getInt("id"));
        person.setName(adapted.getString("name"));
        return person;
    }
}

Furthermore, we’ll assign the adapter to our JsonbConfig instance:

JsonbConfig config = new JsonbConfig().withAdapters(new PersonAdapter());
Jsonb jsonb = JsonbBuilder.create(config);

And we’ll get the following JSON representation:

{
    "id":1, 
    "name":"Jhon"
}

6. Conclusion

In this tutorial, we saw an example of how to integrate the JSON-B API with Java applications using the available implementations, along with examples of customizing serialization and deserialization at both compile and runtime.

The complete code is available, as always, over on Github.