JSON in Java With Gson: A Practical Guide

Gson is Google’s JSON library for Java, and it’s often seen as a simpler alternative to Jackson, especially for smaller projects or when you don’t need all the advanced configuration options Jackson offers. The API is leaner: fewer annotations, less configuration, more predictable behavior out of the box.

Adding the dependency

Maven:

<!-- check Maven Central for the latest Gson version -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.11.0</version>
</dependency>

Gradle:

// check Maven Central for the latest Gson version
implementation 'com.google.code.gson:gson:2.11.0'

Converting JSON into an object (deserialization)

// java
public class Person {
    private String name;
    private int age;

    // getters and setters
    public String getName() { return name; }
    public int getAge() { return age; }
}

// java
import com.google.gson.Gson;

Gson gson = new Gson();

String json = "{\"name\": \"Ana\", \"age\": 30}";
Person person = gson.fromJson(json, Person.class);

System.out.println(person.getName()); // Ana

Notice that, unlike Jackson, Gson doesn’t require getters/setters to work. It can populate private fields directly via reflection, even without them. The getters above are just for you to access the data afterward, not a Gson requirement.

Converting an object into JSON (serialization)

// java
Person person = new Person();
person.setName("Ana");
person.setAge(30);

String json = gson.toJson(person);
System.out.println(json); // {"name":"Ana","age":30}

Formatting the output JSON (pretty print)

In Gson, this is configured when you create the Gson object, using GsonBuilder.

// java
import com.google.gson.GsonBuilder;

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

String json = gson.toJson(person);

Mapping fields with different names

Just like Jackson’s @JsonProperty, Gson has its own annotation for this: @SerializedName.

// java
public class Person {
    @SerializedName("full_name")
    private String fullName;
}

This maps the JSON key full_name to the Java field fullName.

Working with lists

Unlike Jackson (which uses TypeReference), Gson uses TypeToken.

// java
import com.google.gson.reflect.TypeToken;
import java.util.List;

String json = "[{\"name\": \"Ana\"}, {\"name\": \"John\"}]";

List<Person> people = gson.fromJson(json, new TypeToken<List<Person>>(){}.getType());

The pattern is conceptually similar (both exist to work around the same Java type erasure problem), only the specific syntax of each library differs.

Handling parse errors

// java
try {
    Person person = gson.fromJson(invalidJson, Person.class);
} catch (JsonSyntaxException e) {
    System.out.println("Error processing JSON: " + e.getMessage());
}

A behavior difference worth noting: missing fields

If a key is missing from the JSON, Gson simply leaves the corresponding field as null (or the primitive type’s default value), without throwing an error.

// java
String json = "{\"name\": \"Ana\"}"; // missing "age"
Person person = gson.fromJson(json, Person.class);

System.out.println(person.getAge()); // 0 (int default value)

This differs from the default behavior of stricter libraries, which may throw an error for missing required fields. Worth keeping in mind if your use case depends on validating that all expected fields were provided.

Gson vs Jackson: when to use each

	Gson	Jackson
Learning curve	Simpler	More features, more configuration
Requires getters/setters	No	Recommended
Spring Boot integration	Manual	Native (Spring Boot’s default)
Best for	Smaller projects, Android	Larger projects, REST APIs with Spring

Quick checklist

• Using @SerializedName to map JSON keys with names different from your Java fields?
• Using TypeToken (not List.class directly) to deserialize lists?
• Aware that missing fields in the JSON don’t throw an error, they just get the default value?
• Handling JsonSyntaxException in code that receives JSON from external sources?

To quickly validate a JSON before mapping it to a Java class, paste it into JSON Validator.