Gson @SerializedName to Change Field Name Mapping

In this Gson @SerializedName example, learn to change the name of fields between JSON and Java objects during the serialization and deserialization processes.

1. @SerializedName Annotation

By default, we assume that the Java model class and the JSON will have the exact same field names.

But sometimes, it is not the case and certain field names differ. In this situation. we have to map the someName in JSON to someOtherName in Java class. This is where @SerializedName annotation helps.

@SerializedName annotation indicates that the annotated member should be serialized to JSON with the provided name value in the annotation attribute. This annotation will override any FieldNamingPolicy, including the default field naming policy, that may have been using the GsonBuilder class.

Note that the value you specify in this annotation must be a valid JSON field name.

1.1. Annotation attributes

The @SerializedName annotation accepts two attributes:

  • value – the desired name of the field when it is serialized or deserialized.
  • alternate – the alternative names of the field when it is deserialized. It provides more possible names other than ‘value’ attribute. If there are multiple fields that match one property, Gson will use the one that is processed last.

Remember, alternate option to have multiple names is limited to deserialization. In serialization, it will not have any impact.

2. Custom Field Names during Serialization

Let us take an example of Employee class with only 4 fields. We want to create JSON where "email" is written as the field name "emailId".

public class Employee 
    private Integer id;
    private String firstName;
    private String lastName;
    @SerializedName(value = "emailId", alternate = "emailAddress")
    private String email;

Let’s serialize one Employee record and see the JSON output.

Employee emp = new Employee(1001, "Lokesh", "Gupta", "");
Gson gson = new GsonBuilder().setPrettyPrinting().create();  

Program output.

  "id": 1001,
  "firstName": "Lokesh",
  "lastName": "Gupta",
  "emailId": ""

3. Changing Field Names during Deserialization

Java program to map different field names during deserializing JSON to Java class.

  "id": 1001,
  "firstName": "Lokesh",
  "lastName": "Gupta",
  "email": "",
  "emailAddress": ""
String json = "{'id': 1001,"
    + "'firstName': 'Lokesh',"
    + "'lastName': 'Gupta',"
    + "'emailId': '',"
    + "'emailAddress': ''}";
Gson gson = new GsonBuilder().setPrettyPrinting().create(); 
Employee emp = gson.fromJson(json, Employee.class);

Program output.

Employee [id=1001, firstName=Lokesh, lastName=Gupta,]

Notice the program output. we had two matches for email field i.e. emailId and emailAddress. The last occurrence was for "emailAddress", so it’s value got populated into Employee object.

Drop me your questions related to mapping multiple different names to member fields in Java class using Gson @SerializedName annotation.

Happy Learning !!


Notify of
Most Voted
Newest Oldest
Inline Feedbacks
View all comments

About Us

HowToDoInJava provides tutorials and how-to guides on Java and related technologies.

It also shares the best practices, algorithms & solutions and frequently asked interview questions.

Our Blogs

REST API Tutorial

Dark Mode

Dark Mode