Handling Multiple Names for JSON Field in Kotlin

1. Overview

In this tutorial, we’ll discuss a few methods we can use to handle multiple names for a JSON field in Kotlin. Essentially, handling multiple names for a JSON field involves either renaming the field according to our preference or matching the naming conventions of different data sources or APIs.

This can improve the readability and maintainability of our code by using more meaningful or consistent names for the properties in our data class.

2. Reasons to Handle JSON Fields

Let’s look at a couple of reasons why we sometimes need to handle fields differently in our JSON.

First, let’s take the case where the source of our data, such as an API, evolves and new field names are introduced to our JSON, but the old fields are still present. We need to ensure backward compatibility with the previous consumers of the API.

Second, suppose we’re integrating with other external systems that provide us with JSON data and they have their own naming schemes for fields that we require in our data, too. We need to handle these fields in our JSON to ensure they align with the data class properties used in our system.

3. Using JsonNames

We can use the @JsonNames annotation to handle multiple names for a JSON field. To demonstrate this, we’ll create a simple data class.

Let’s see the @JsonNames annotation in action:

@Serializable
data class User(
    @JsonNames("uid")
    val id: String
)

fun handleJsonWithJsonNames() {
    val json = """{"uid":"1"}"""
    val user = Json.decodeFromString<User>(json)
    assertEquals(user.id) // Output: 1
}

Here, we used @JsonNames on the id property of the User data class. The annotation accepts multiple names as arguments, allowing us to specify alternative names for our JSON field.

4. Using the SerialName Annotation

Another solution to handle multiple names for our JSON field is using the @SerialName annotation.

Let’s see an example of using the @SerialName annotation on a data class:

@Serializable
data class Car(
    @SerialName("which_model")
    val model: String
)

fun handleJsonNamesWithSerialName() {
    val carJson = """{"which_model":"Altima"}"""
    val car = Json.decodeFromString<Car>(carJson)
    assertEquals(car.model) // Output: Altima
}

In this code, we applied the @SerialName annotation on our model property. This allows it to be deserialized from JSON fields as either the field name model, or as which_model. In this case, the serializer will automatically handle the which_model property and eventually map it to the model property of our data class.

5. Conclusion

In this article, we discussed two methods we can use to handle multiple names for JSON fields in Kotlin. These include using the @SerialName and @JsonNames annotations to help us automatically handle multiple properties from our JSON data to match our own naming conventions in data classes. We also went through some of the reasons we may need to handle or rather rename the properties of our JSON fields in our data classes.

The full implementation of these examples can be found over on GitHub.