Gson @SerializedName

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 !!

Was this post helpful?

Join 8000+ Awesome Developers, Like YOU!

4 thoughts on “Gson @SerializedName”

  1. This is INCORRECT: “Notice the program output. we had two matches for email field i.e. email and emailAddress. The last occurrence was for “emailAddress”, so it’s value got populated into Employee object.”

    The name of the field i.e. email in this case does not to Gson. If we have value = “XYZ” and alternate=”DEF”, then first it looks for XYZ, if not then it looks for DEF[Only during deserialization].

      • Your example works as intended and Gson will indeed do the one processed last like you expect, but your example does have a flaw. In you have

        + “’email’: ‘’,”
        + “’emailAddress’: ‘’}”;

        but in the employee class you have @SerializedName(value = “emailId”, alternate = “emailAddress”)

        In change ’email’ to ’emailId’


Leave a Comment

About HowToDoInJava

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

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