Gson: Convert Java Objects to JSON and Back
Gson does one job — turning Java objects into JSON and back — without asking you to annotate the class first. That's the whole pitch, and for code you don't own it still holds up. The catch sits right in the project's own README: Gson calls itself maintenance mode now and tells Android developers to look at Kotlin Serialization instead. Treat it as a stable, finished tool, not one still growing.
What is Gson
Gson is a Java library from Google that converts Java objects into JSON and converts JSON strings back into Java objects. It works through reflection, so it doesn't require annotations on a class or access to that class's source code before serializing it. The README lists deep Java Generics support and handling complex object graphs as explicit design goals. Two methods carry the workflow: toJson() and fromJson().
Core features
- ✓toJson() and fromJson() handle the whole conversion in both directions, with no other required setup.
- ✓Works on classes without annotations — including pre-existing objects you don't have the source code for.
- ✓Extensive support for Java Generics, listed in the README as a goal most competing libraries at the time skipped.
- ✓Handles arbitrarily complex object graphs: deep inheritance hierarchies and heavy use of generic types.
- ✓Provides a JPMS module descriptor (module name com.google.gson) ensuring outofbox use on Java 9 and newer.
- ✓Optional java.sql module support adds default adapters for SQL date and time classes when that module is present.
- ✓Can fall back to the JDK-internal Unsafe class to construct objects that have no no-args constructor.
Basic usage with toJson and fromJson
The README documents the API by method name rather than a full code sample: the two calls you reach for are toJson(), to turn a Java object into a JSON string, and fromJson(), to turn a JSON string back into a Java object. Beyond those two calls, exact method signatures and step-by-step examples live in the separate User Guide and API Javadoc linked from the repo — the top-level README itself doesn't walk through a worked example.
Adding Gson to your project
Add Gson as a dependency with Gradle: implementation 'com.google.code.gson:gson:2.14.0' inside your dependencies block. With Maven, add the dependency block with groupId com.google.code.gson, artifactId gson, and version 2.14.0. Prebuilt jars are also available directly from Maven Central. Minimum Java version depends on which Gson release you install: 2.12.0 and newer need Java 8, 2.9.0 through 2.11.0 need Java 7, and 2.8.9 or older run on Java 6.
Strengths
- ✓No annotations required — works on classes you don't own or can't modify the source of.
- ✓Full Java Generics support built in as a stated design goal, not bolted on afterward.
- ✓Handles deep, complex object graphs, including multi-level inheritance hierarchies.
- ✓Ships a proper JPMS module descriptor for Java 9+, while older releases still cover Java 6 and 7.
Known limitations
- △According to the README, the project is officially in maintenance mode: current bugs are fixed but substantial new features probably won't be introduced.
- △The maintainers themselves discourage using Gson on Android, since its reflection-based approach can break under code shrinking and obfuscation in release builds.
- △Only fully supports Java — using it from Kotlin or Scala can produce confusing or incorrect behavior around non-null types and constructors with default arguments.
- △Falls back to the JDK-internal sun.misc.Unsafe class for classes without a no-args constructor, and that class isn't guaranteed to be available in every environment.
Alternatives to Gson
Frequently asked questions
Gson is in maintenance mode, per its own README: existing bugs get fixed, but large new features are unlikely. Anyone wanting to add a feature is asked to open a GitHub issue for discussion first, rather than send a pull request directly.
Gson runs on Android, but the README actively discourages it: reflection doesn't play well with code shrinking and obfuscation in release builds. The maintainers point to Kotlin Serialization instead, or to configuring ProGuard/R8 if you keep using Gson.
Gson 2.12.0 and newer need Java 8; 2.9.0 through 2.11.0 need Java 7; 2.8.9 and older run on Java 6. For projects using Java 9 or newer, newer releases include a JPMS module descriptor named com.google.gson.
Gson does not require annotations on your classes. That's one of its core design goals: converting arbitrary Java objects to JSON even when you don't have the source code to add annotations to, unlike most other Java JSON libraries at the time.
Gson treats full Java Generics support as a core design goal, something the README says most competing libraries did not handle well. It's listed alongside working with pre-existing, unmodifiable objects as a reason the library was built.
Gson is released under the Apache 2.0 license, copyright Google Inc. The README also carries a disclaimer that Gson is not an officially supported Google product, despite living under the google organization on GitHub.
The problem it solves
Before Gson, converting a Java object to JSON usually meant either writing the mapping by hand or reaching for a library that forced you to annotate every class it touched. That's fine for code you own. It breaks down for objects from a third-party jar, a legacy module, or anything else you can't add an annotation to. Gson's answer is to skip the annotation requirement and the Generics-shy reflection some competitors used, so toJson() and fromJson() work on classes exactly as they already exist.
Best use cases
- •Serializing an object from a third-party jar or legacy module you can't add annotations to.
- •Converting deeply nested or heavily generic data structures to and from JSON without hand-written parsing.
- •Adding JSON support to an existing Java codebase where refactoring every class for annotations isn't practical.
- •Reading and writing SQL date/time values through the optional java.sql module adapters.
Who should try it — and who should skip
Gson fits a Java developer who needs to serialize objects they don't fully control — a class from a dependency jar, a legacy module, anything without room to add annotations — and who wants full Generics support without extra configuration. It's a poor fit for an Android app built with ProGuard/R8 shrinking, where the README itself points to Kotlin Serialization instead, and for a Kotlin or Scala codebase leaning on non-null types or default constructor arguments, since Gson's reflection can misread both.
Want a second opinion on gson?
Ask an AI that can read this page — one click and you get its take on gson.
