Core Java

Gson Expose vs SerializedName

Hello. In this tutorial, we will understand Gson Expose vs SerializedName annotations.

1. Introduction

Gson is a Java library developed by Google that provides a simple and flexible way to convert Java objects to JSON (JavaScript Object Notation) and vice versa. JSON is a lightweight data interchange format that is commonly used for representing structured data, making it easy to exchange information between different systems and programming languages.

Gson allows you to serialize (convert from Java objects to JSON) and deserialize (convert from JSON to Java objects) objects with just a few lines of code. It handles complex data structures, custom object serialization/deserialization, and various data types seamlessly.

Key features of Gson include:

  • Serialization: Gson can convert Java objects into JSON strings. This is useful when you need to send data to a server or store data in a file.
  • Deserialization: Gson can convert JSON strings back into Java objects, making it simple to process data received from a server or read from a file.
  • Custom Serialization/Deserialization: You can define custom serializers and deserializes for your classes if they have specific serialization requirements that aren’t handled by the default behavior.
  • Handling Complex Objects: Gson can handle nested and complex data structures, arrays, lists, maps, and other Java collections.
  • Annotations: Gson provides annotations that allow you to control the serialization and deserialization process. For example, you can use annotations to change the field names in JSON, exclude fields from serialization, and more.
  • Type Handling: Gson can handle various Java types, including generics, making it suitable for a wide range of use cases.
  • Pretty Printing: Gson can format JSON output to make it more human-readable, which is useful for debugging purposes.

2. Understanding Gson Annotations: @Expose and @SerializedName

The @Expose and @SerializedName annotations are part of the Google Gson library, which facilitates the serialization and deserialization of Java objects to and from JSON representation. These annotations offer customization options to control field inclusion, exclusion, and field name mappings.

Let’s explore each annotation in detail.

2.1 @Expose Annotation

The @Expose annotation is utilized to determine which fields should be included or excluded during serialization and deserialization. Fields annotated with @Expose will be serialized and deserialized only if the annotation’s serialize and deserialize properties are set to true. If either property is set to false, the field will be excluded from the process.

2.1.1 Example

In this example, includedField will be included in both serialization and deserialization, while excludedField will be included during deserialization but not during serialization. The extraField field, lacking the annotation, won’t be included in the JSON.

package com.jcg.example;


public class MyClass {
    @Expose(serialize = true, deserialize = true)
    private String includedField;

    @Expose(serialize = false, deserialize = true)
    private String excludedField;

    private String extraField;
    // Constructors, getters, setters, etc.

2.1.2 Usage

This annotation is particularly useful when you have complex objects and want to optimize the data transferred in JSON representations.

  • Selective Serialization: By applying @Expose to specific fields, you indicate that these fields should be candidates for serialization.
  • Efficiency and Customization: Not all fields need to be included in JSON representations. You can optimize data transfer by exposing only essential fields.
  • Security and Privacy: Some fields might contain sensitive information that should not be exposed. @Expose helps prevent unintended data exposure.

2.2 @SerializedName Annotation

The @SerializedName annotation allows you to define a custom name for a field during serialization and deserialization. This is particularly useful when you need to map Java field names to different names in the JSON representation.

2.2.1 Example

In this example, firstName will be represented as "first_name" in the JSON, and lastName will be represented as "last_name".

package com.jcg.example;


public class Person {
    private String firstName;

    private String lastName;

    // Constructors, getters, setters, etc.

2.2.2 Usage

It simplifies field-key mapping, especially when there are naming discrepancies between the two.

  • Simplified Mapping: Java field names might not always match JSON keys. @SerializedName facilitates easy mapping, ensuring accurate conversion.
  • Field-Key Consistency: When JSON keys deviate from Java field names, code readability might suffer. @SerializedName helps maintain naming consistency.
  • Flexible Integration: Use @SerializedName to accommodate external API specifications or legacy data formats without altering your Java class structure.

3. Combining @Expose and @SerializedName Annotations

You can use both annotations together to control serialization and deserialization behavior and to customize field names:

public class Employee {
    @Expose(serialize = true, deserialize = true)
    private String employeeId;

    @Expose(serialize = true, deserialize = false)
    private String fullName;

    // Constructors, getters, setters, etc.

In this example, employeeId will be serialized and deserialized using the JSON key "emp_id". On the other hand, fullName will be included during serialization but excluded during deserialization, and it will use the JSON key "full_name".

Remember that both annotations require the Gson library, and you need to configure a Gson instance with appropriate settings, including the processing of @Expose annotations. This can be achieved using the GsonBuilder:

Gson gson = new GsonBuilder()
    .excludeFieldsWithoutExposeAnnotation() // Process @Expose annotations

This configuration ensures that fields marked with @Expose are processed based on their serialize and deserialize properties.

4. Difference between Gson Annotations: @Expose and @SerializedName

ControlControls inclusion/exclusion of fields.Doesn’t control inclusion/exclusion, but specifies field names.
Propertiesserialize and deserializeN/A
FunctionDetermines whether to process a field.Maps field name in Java class to JSON key.

5. Conclusion

In conclusion, the @Expose and @SerializedName annotations are valuable features provided by the Gson library, contributing to enhanced control and customization of the serialization and deserialization processes when working with Java objects and JSON representations. These annotations offer developers the flexibility to tailor the serialization and deserialization behaviors according to their specific requirements, making Gson a versatile and powerful tool for data conversion tasks.

The @Expose annotation serves as a gatekeeper, allowing developers to selectively choose which fields within a Java class should be included in the serialization process. By applying this annotation to class fields, developers can mark them as candidates for serialization, thus improving efficiency and fine-tuning the data that gets converted to JSON. This capability is particularly useful when dealing with complex objects or when certain fields need to be excluded from serialization to minimize data size or security concerns.

On the other hand, the @SerializedName annotation facilitates seamless mapping between Java class fields and JSON keys. This is essential when the field names in Java classes do not directly correspond to the keys in the JSON representation. Developers can apply this annotation to class fields and provide the corresponding JSON key as its argument. This ensures that Gson correctly identifies the appropriate JSON key when serializing or deserializing data, even when the naming conventions between Java and JSON differ.

Both annotations together provide a robust mechanism for aligning Java classes with their JSON counterparts, irrespective of potential differences in naming conventions, while still allowing for selective inclusion/exclusion of fields during serialization. This powerful combination empowers developers to maintain consistency in their codebase while accommodating varying requirements between their Java application and the JSON data format.

In essence, the @Expose and @SerializedName annotations exemplify Gson’s commitment to offering developers comprehensive tools for handling data conversion tasks. These annotations foster greater control, maintainability, and adaptability in the serialization and deserialization processes, ultimately contributing to more efficient and effective communication between Java applications and external systems through JSON representations. By leveraging these annotations, developers can strike a balance between streamlined data exchange and the nuanced control over data transformation that modern applications often demand.


An experience full-stack engineer well versed with Core Java, Spring/Springboot, MVC, Security, AOP, Frontend (Angular & React), and cloud technologies (such as AWS, GCP, Jenkins, Docker, K8).
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button