Gson 2.14.0: JSON for Java Objects You Cannot Annotate

The problem Gson was built around: classes you cannot edit

Most Java JSON libraries ask you to annotate your model classes. That works until the class is not yours. A dependency you pulled from Maven Central, a class generated by a build step, or a legacy type inside a jar you cannot rebuild all fall outside that model. Gson's stated design goal is to convert Java objects to JSON and back for arbitrary classes, including pre-existing objects that you do not have source code for. The second goal is generics: the README claims most alternatives do not fully support Java Generics, and Gson treats that as a first-class requirement rather than an add-on. The audience is therefore server-side Java developers working with types they do not control, and codebases with deep inheritance hierarchies and heavily parameterized types.

How Gson turns an object into JSON without annotations

Gson works through reflection at runtime. Two entry points do the work: toJson() walks an object graph and emits JSON text, and fromJson() reads JSON text and reconstructs an object of a requested type. Because the type is supplied at the call site, Gson can resolve generic parameters that a plain reflective walk would erase. Custom representations are supported through adapters, which is the documented escape hatch when the default mapping does not match what you need. The repository layout reflects that architecture: the core lives under gson/, with separate top-level directories for proto/ and extras/, plus test-jpms/ and test-shrinker/ for module-system and shrinking behaviour. The design document, GsonDesignDocument.md, is where the project records the trade-offs it made, including a comparison against other Java JSON libraries. That document is the honest place to look if you want to understand why Gson behaves the way it does rather than reading the API surface alone. One runtime detail matters for construction: when the jdk.unsupported module is present, Gson can use sun.misc.Unsafe to instantiate classes that have no no-args constructor. The README is explicit that Unsafe is not available in all environments and that relying on it has pitfalls, and it points to GsonBuilder.disableJdkUnsafe() as the switch.

Adding Gson as a Maven or Gradle dependency

Gson is published to Maven Central under the coordinates com.google.code.gson:gson, and the README gives both build-tool forms. For Gradle, the dependency block is:

dependencies {
  implementation 'com.google.code.gson:gson:2.14.0'
}

For Maven, the same artifact is declared with the groupId, artifactId and version elements:

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

After the build resolves, the Gson classes are on the compile classpath and no annotation processor runs. The README also links jar downloads from Maven Central for projects that are not using either build tool. Version choice is constrained by the runtime: Gson 2.12.0 and newer requires Java 8, Gson 2.9.0 to 2.11.0 requires Java 7, and Gson 2.8.9 and older requires Java 6. On Android the floor is different again, with Gson 2.15.0 and newer requiring API level 24, Gson 2.11.0 and newer requiring API level 21, and Gson 2.10.1 and older requiring API level 19. Note that 2.15.0 is listed in the requirements table but does not appear among the recent releases, so check Maven Central for what is actually published before pinning that version.

Where Gson is the wrong tool

The README contains three warnings that are unusual for a library of this age, and they are worth reading before anything else. First, Gson is in maintenance mode: existing bugs will be fixed, but large new features will likely not be added, and feature proposals are expected to arrive as GitHub issues first. Second, the project does not recommend Gson for interacting with JSON on Android. The reason given is that Gson's open-ended reflection does not survive the shrinking, optimization and obfuscation passes that Android release apps should run, which produces runtime crashes when fields are missing or renamed. The README directs Android users to Kotlin Serialization, which generates code instead of reflecting, and notes it is faster on Android devices. Third, Gson's focus is Java. Kotlin's non-null types and constructors with default arguments are not supported, and the README warns this can lead to confusing and incorrect behaviour, recommending a library with explicit support for the language instead. That is a real correctness risk, not a stylistic preference. There is also a build-versus-use distinction: building Gson itself needs JDK 17 or newer with JDK 21 recommended, while using the library only needs the Java version from the table.

Gson versus Jackson, and versus code generation

Jackson is the comparison the search data keeps returning, and the architectural difference is the interesting part. Gson's model is a runtime reflective mapper with adapters for custom representations. Jackson's is a streaming parser and generator with a databind layer on top, which is why Jackson exposes a low-level token API that Gson does not centre on. If you need to stream a large document and never materialize the whole object graph, that is a different shape of tool. The second alternative is the code-generation family, represented in the README by Kotlin Serialization. It avoids reflection entirely, which is exactly why the README recommends it for Android: no reflective field lookup means nothing for the shrinker to break. The cost is that you need the compiler plugin and, in Java terms, annotations or generated adapters, which brings back the original problem for classes you cannot edit. Gson's niche is the middle ground: no annotations required, no code generation step, at the price of reflection and everything that follows from it.

Maintenance status, releases and licence

The repository is not archived, and the last push was on 2026-09-16. That is recent activity, but it should be read alongside the README's own statement that Gson is in maintenance mode, which is the project's description of its intent rather than an inference from commit dates. On releases, the recent list shows gson-parent-2.14.0 on 2026-04-23, gson-parent-2.13.2 on 2025-09-10, and gson-parent-2.13.1 on 2025-04-24. The cadence is roughly one minor release per year recently, with patch releases in between, and the changelog lives in CHANGELOG.md with per-release notes on GitHub. Upgrade cost is dominated by the version tables rather than by API churn: raising the Gson version can raise the minimum Java version or the minimum Android API level, so a bump that looks trivial in a Gradle file can break an older runtime. Gson is released under Apache-2.0, and the README carries the standard disclaimer that this is not an officially supported Google product. Apache-2.0 is a permissive licence, but whether its patent and notice terms fit your distribution model is a question for your own legal review, not something this article can settle.

Editorial conclusion

Adopt Gson for server-side Java code that must serialize third-party or generated classes you cannot annotate, and where Java 8 or newer is available. Do not adopt it for Android release builds, Kotlin or Scala data models, or projects that need new features, because the README puts the project in maintenance mode and points Android users at Kotlin Serialization. Before committing, verify the Java and Android API levels your build targets against the version table in the README, and check whether your classes rely on Unsafe for construction, since GsonBuilder.disableJdkUnsafe() changes that path.

Frequently asked questions

Official sources

1. google/gson on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases