How to let Java library users choose between JSON parsing frameworks?

Question

I am developing a Java library that can be used to call a certain web API that is using JSON data format to pass information. Said library will only contain data classes according to the data structure defined by the API spec. Code required to call the API will be placed in a second library.

In Java enterprise applications, there are several JSON parsing libraries available, like JSON-B or Jackson. I want to design my library to be somewhat agnostic of the underlying JSON implementation.

Let's assume my library has a class Article:

public class Article {
    String id;
    String headline;
    String content;
}

To make that class suitable for use in JSON-B-enabled applications, I would have to provide the following annotations with my class, along with a project dependency to e.g. jakarta.json.bind:jakarta.json.bind-api:

public class Article {
    @JsonbProperty("id")
    String id;

    @JsonbProperty("headline")
    String headline;

    @JsonbProperty("content")
    String content;
}

To make that class suitable for use in Jackson-enabled applications, I would have to provide the following annotations with my class, along with a project dependency to e.g. com.fasterxml.jackson.core:jackson-annotations:

public class Article {
    @JsonProperty("id")
    String id;

    @JsonProperty("headline")
    String headline;

    @JsonProperty("content")
    String content;
}

I have seen libraries for Quarkus offering distinct versions for both frameworks, like quarkus-resteasy-reactive-jsonb and quarkus-resteasy-reactive-jackson, but those do not have POJO classes to serialize. I could provide three modules of my library, a base version and versions for JSON-B and Jackson, but I can't wrap my head around how to do it without duplicating / extending lots of classes and dependencies.

score 1 · Answer 1 · answered Jul 09 '23 at 16:56

First, it's worth noting that @JsonProperty annotations are not (usually) required for Jackson. Still, depending on the classes being serialized, some annotations may be needed. In this case, I'd simply add both sets of annotations to the data class - after all, excess annotations do no harm if their corresponding framework is not asked to process that class.

To do so, your maven module will want to declare a dependency on both annotation jars. If you're concerned about your clients receiving an unnecessary annotation jar, you can declare your dependency optional, so it's only used during compilation of your data class, but not available at runtime unless your users declare a dependency themselves. The annotation JARs being absent causes no issue because the Java runtime ignores annotations whose definition is missing.

Ken Chan · Answer 2 · 2023-07-09T16:41:11.623

The idea is that for each of the individual JSON library modules , you have to develop some generic codes that can serialise/deserialise between a given POJO and JSON by using that JSON library 's API.

The annotation approach provided by the JSON library is just a high level way for processing the JSON. There should be the some way to do the same thing without POJO and annotations and you should check each of the JSON library for how to do that when developing those generic codes. For example in Jackson, you can represent the JSON structure as a map instead of POJO

To keep the POJO to be agnostic of any JSON libraries , you can also consider to define your own annotations for annotating the POJO. Those generic codes in each JSON modules can then make use of it to make the decision.

How to let Java library users choose between JSON parsing frameworks?

2 Answers2