@Expose vs @SerializedName Annotations in Gson

1. Introduction

Gson is an open-source Java library developed by Google to facilitate the conversion of objects to JSON and vice versa. It provides efficient serialization and deserialization techniques and supports complex objects.

Libraries like Gson provide support for mapping JSON directly to POJOs. However, sometimes, specific attributes must be excluded from serialization and deserialization.

In this tutorial, we’ll discuss two common and essential annotations used with the Gson library, @Expose and @SerializedName. While both of these annotations are related to the serializability and deserializability of attributes, they have their use cases.

2. Setup of Gson

To start using Gson, we add its Maven dependency in our pom.xml:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.10.1</version>
</dependency>

3. @Expose in Gson

Gson’s default behavior is to serialize and deserialize all fields in a POJO class unless specified otherwise. The @Expose annotation can override this behavior and control the inclusion or exclusion of a specific field from serialization and deserialization.

Gson includes only the fields annotated with @Expose in the JSON if their serialize and deserialize properties are set to true. The default value for serialize or deserialize is true.

Let’s see an example. We’ll use a User class with attributes like id, name, age, and email. Email is sensitive information, so we’ll exclude it from being serialized in the output JSON:

public class User {

    @Expose
    String name;

    @Expose
    int age;

    @Expose(serialize = true, deserialize = false)
    long id;
    
    @Expose(serialize = false, deserialize = false)
    private String email;

    // Constructors, Getters, and Setters
}

In the above code snippet, we annotate the name and age fields with @Expose. The absence of explicit serialize and deserialize properties signifies that they’re defaulted to true.

We should also notice that the email attribute has both of the annotations set to false. Therefore, the serialized JSON ignores the email field. However, we should use excludeFieldsWithoutExposeAnnotation() while creating the GsonBuilder instance for this to happen.

On the other hand, for id, the serialization process includes it, whereas deserialization ignores any id present in the JSON:

@Test
public void givenUserObject_whenSerialized_thenCorrectJsonProduced() {
    User user = new User("John Doe", 30, "[email protected]");
    user.setId(12345L);

    Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create();
    String json = gson.toJson(user);

    // Verify that name, age, and id are serialized, but email is not
    assertEquals("{\"name\":\"John Doe\",\"age\":30,\"id\":12345}", json);
}

@Test
public void givenJsonInput_whenDeserialized_thenCorrectUserObjectProduced() {
    String jsonInput = "{\"name\":\"Jane Doe\",\"age\":25,\"id\":67890,\"email\":\"[email protected]\"}";

    Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation()
      .create();
    User user = gson.fromJson(jsonInput, User.class);

    // Verify that name and age are deserialized, but email and id are not
    assertEquals("Jane Doe", user.name);
    assertEquals(25, user.getAge());
    assertEquals(0, user.getId()); // id is not deserialized
    assertNull(user.getEmail()); // email is not deserialized
}

We see in the first test that the serialized JSON doesn’t contain the email attribute. In the second unit test, we assert that the deserialized User object ignores the email field from its JSON.

4. @SerializedName in Gson

Let’s understand the use of the @SerializedName annotation in Gson. When we create the Java class and define its attributes, the JSON representation may require a name different from the one defined in the class. This annotation maps a POJO attribute to a specific name in its serialized JSON representation.

Following with our previous example, let’s say this time we want the JSON representation of User to have firstName as the field name instead of name:

public class User {

    @Expose
    @SerializedName("firstName")
    String name;
}

Our unit tests should now assert the firstName field:

@Test
public void givenUserObject_whenSerialized_thenCorrectJsonProduced() {
    User user = new User("John Doe", 30, "[email protected]");
    user.setId(12345L);

    Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create();
    String json = gson.toJson(user);

    assertEquals("{\"firstName\":\"John Doe\",\"age\":30,\"id\":12345}", json);
}

@SerailizedName supports an additional attribute called alternate, which takes in a list of alternate names for the attribute and tells the parser to look for either of the values while deserializing. This is a powerful feature when the attribute name might vary depending on external or legacy systems.

Let’s consider a system that uses fullName instead of firstName. We can decode these correctly by filling in the alternate attribute properly:

public class User {

    @Expose
    @SerializedName(value = "firstName", alternate = { "fullName", "name" })
    String name;
}

@Test
public void givenJsonWithAlternateNames_whenDeserialized_thenCorrectNameFieldMapped() {
    String jsonInput1 = "{\"firstName\":\"Jane Doe\",\"age\":25,\"id\":67890,\"email\":\"[email protected]\"}";
    String jsonInput2 = "{\"fullName\":\"John Doe\",\"age\":30,\"id\":12345,\"email\":\"[email protected]\"}";
    String jsonInput3 = "{\"name\":\"Alice\",\"age\":28,\"id\":54321,\"email\":\"[email protected]\"}";

    Gson gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().create();

    User user1 = gson.fromJson(jsonInput1, User.class);
    User user2 = gson.fromJson(jsonInput2, User.class);
    User user3 = gson.fromJson(jsonInput3, User.class);

    // Verify that the name field is correctly deserialized from different JSON field names
    assertEquals("Jane Doe", user1.getName());
    assertEquals("John Doe", user2.getName());
    assertEquals("Alice", user3.getName());
}

We could correctly deserialize the name attribute from the input JSON payloads, having fullName and firstName as the attribute names.

5. Differences Between @SerializedName and @Expose

Let’s quickly summarise the primary differences between the two annotations:

6. Conclusion

In this article, we saw how @SerializedName and @Expose work and how we can use them to handle JSON serializing and deserializing in Java. We also highlighted the major differences between the two.