Released with Jakarta EE 10

New Features in Jakarta JSON Processing and JSON Binding

David Kral
© Shutterstock / Marharyta Tsapenko

This article recaps some of the significant new features and changes found in JSON Binding 3.0 and JSON Processing 2.1, the specification versions that will release with Jakarta EE 10. These include multiple clarifications and enhancements.

The Jakarta JSON Processing and Jakarta JSON Binding specifications help Jakarta EE users process JSON documents. Here’s a recap of the most significant new features and changes in JSON Binding 3.0 and JSON Processing 2.1, the specification versions that will be released with Jakarta EE 10.

JSON Processing 2.1: Repositories Separated and JsonNumber Creation Improved

The JSON Processing 2.1 specification includes multiple clarifications and enhancements. These are some of the most notable ones:

  • JSON Processing previously used the same repository for its implementation and API. The new release separates them to make the specification more vendor neutral. The newly separated implementation is called Parsson.
  • Since API version 1.1, there have been several methods for creating a JsonNumber from different number types, including int, long, and double. However, there was no method for the general number type. This has been fixed in the new release.
  • Technology compatibility kit (TCK) tests have been removed from the overall TCK test repository. This change does not directly affect users but allows implementors of the JSON Processing API to run tests as easily as any other JUnit test.

SEE ALSO: Getting Started with the DataStax Astra Java SDK

JSON Binding 3.0: Easier Handling of Polymorphic Types

The JSON Binding 3.0 specification includes many great new features and functionality improvements as well as various alignments and clarifications.

Previously, handling of polymorphic types was somewhat difficult to set up and usually required creating advanced deserializers and logic. In the new release, you can handle polymorphic types using the @JsonbTypeInfo annotation. First, you need to create an alias for all of the possible subclasses in the annotated class. You can then use those aliases to ensure secure mapping of subclasses to or from the JSON document.

Here’s an example of the model:

      @JsonbSubtype(alias = "dog", type = Dog.class)
      @JsonbSubtype(alias = "cat", type = Cat.class)
interface Animal {}

class Dog implements Animal {
    public String isDog = true;
class Cat implements Animal {
    public String isCat = true;

When the Dog instance is serialized, it will produce the following JSON output:


Because the type information is stored in the @type property, you can now ensure backwards mapping to the proper type without needing to know it beforehand. You can simply use the fromJSON method on the Jsonb instance to provide the interface or class where @JsonbTypeInfo is defined as a requested type.

Here’s an example:

jsonb.fromJson(json, Animal.class)

This method will return an instance of the class Dog because its alias was present in the JSON document.

JSON Binding 3.0: Relaxed Property Requirements and Quality of Life Changes

The new release also relaxes the requirement for the @JsonbCreator annotated constructor or factory method to include necessary properties in a JSON document when it is deserialized. There are no failures if any of the properties are missing.

The value passed into the creator method is strictly dependent on the type it is being passed into:

  • If the parameter is any of the primitive types, the provided empty value is equal to the default value of the type, such as 0 for int or false for Boolean.
  • If the type is Optional, OptionalInt, OptionalLong, or OptionalDouble, the value passed into the missing parameter is equal to the value provided by the empty method on each of these types.
  • For the other types, a null value is passed as the default value.

Several other smaller improvements are also worth mentioning:

  • Adapters and deserializers can now be used on the parameters of the @JsonbCreator annotated constructors or factory methods.
  • JsonbProperty.nillable() has been deprecated in favour of the @JsonbNillable annotation. This change reduces confusion in advanced null value handling cases.
  • Similar to JSON Processing, the JSON Binding TCK has also been removed from the platform TCK repository. These separated tests can also be run using a JUnit framework.

JSON Binding 3.0 also includes a minor backwards incompatibility in the way JsonbCreator parameters are handled. This will be explained in a future article.

Get Involved in JSON Processing and JSON Binding

We welcome anyone who’s interested to participate in either project. Visit the following links for more information.

Jakarta JSON Processing:

Jakarta JSON Binding:


David Kral

David Kral is a Java software developer at Oracle and a committer to Jakarta JSON Binding, among other projects.

Inline Feedbacks
View all comments