CodeMD repository analysis · example report

google/gson

An analysis of github.com/google/gson as it was on 2026-11-13.

155files analyzed
12features
276quality signals
0security findings

Overview

What the repository is and how it is built, written by AI from the analysis.

Gson

Summary

Gson is a Java library from Google for converting Java objects into their JSON representation and converting JSON strings back into equivalent Java objects. It can work with arbitrary Java objects, including pre-existing ones whose source code you don't have. Unlike many JSON libraries, it doesn't require annotations in your classes, and it fully supports Java Generics.

Gson is in maintenance mode: existing bugs will be fixed, but large new features are unlikely. It is focused on Java. Other JVM languages such as Kotlin or Scala may work, but language-specific features aren't supported. It is also not recommended for Android, because its reflection-based runtime conflicts with shrinking, optimization and obfuscation.

Key features

  • Simple conversion: toJson() turns objects into JSON and fromJson() turns JSON into objects.
  • No source access needed: Unmodifiable, pre-existing objects can be converted without annotations.
  • Extensive Generics support: Parameterized types are serialized and deserialized correctly.
  • Custom representations: Define your own JSON form for objects through type adapters.
  • Complex object graphs: Handles deep inheritance hierarchies and heavy use of generic types.
  • Java records: Serializes and deserializes Java records.
  • SQL date and time adapters: Default adapters are provided when the java.sql module is present.
  • Instantiation without no-args constructors: Gson can use Unsafe when it is available, and this can be disabled.
  • Java module support: A JPMS module descriptor (com.google.gson) is included for Java 9+.
  • Protobuf support: An optional proto module provides a JSON serializer and deserializer for Protocol Buffers messages. It isn't deployed to Maven Central.
  • Shrinker and native-image compatibility: There is ProGuard/R8 guidance, plus tests for shrinking and GraalVM Native Image.

Typical use cases

  • Serializing application data to JSON, and parsing JSON back into Java objects.
  • Converting classes from third-party libraries or other code you can't annotate or modify.
  • Working with generic or deeply nested data models.
  • Customizing how particular types appear in JSON.
  • Using Gson as a named module in Java 9+ projects.
  • Converting Protocol Buffers messages to and from JSON through the optional proto module.

Architecture

Gson is a multi-module Maven project:

  • gson: The core library, published to Maven Central as com.google.code.gson:gson.
  • extras: Supplementary features that aren't included by default. Not deployed to Maven Central.
  • proto: The Protocol Buffers JSON serializer and deserializer. Not deployed to Maven Central.
  • metrics: Internal benchmark tests.
  • test-graal-native-image: Integration tests for GraalVM Native Image, including reflection metadata. These are not enabled by default.
  • test-jpms: Tests that verify the module descriptor against the final JAR.
  • test-shrinker: Integration tests with code shrinking and obfuscation tools such as ProGuard and R8.

Gson 2.12.0 and newer require Java 8. The java.sql and jdk.unsupported JDK modules are optional dependencies. Building requires JDK 17 or newer, and JDK 21 is recommended. Gson is released under the Apache 2.0 license.

Features

12 features found in the code and documentation.

Object-to-JSON conversion

Converts Java objects into their JSON representation with a simple toJson() call.

JSON-to-object conversion

Converts JSON strings into equivalent Java objects with a simple fromJson() call.

Works without source access

Converts pre-existing, unmodifiable objects to and from JSON without requiring annotations or access to their source code.

Extensive Java Generics support

Fully handles generic types so parameterized classes can be serialized and deserialized correctly.

Custom type representations

Lets you define custom JSON representations for objects via type adapters instead of the default mapping.

Complex object graphs

Supports arbitrarily complex objects, including deep inheritance hierarchies and heavy use of generic types.

Java record support

Serializes and deserializes Java records.

Default SQL date/time adapters

Provides built-in adapters for SQL date and time classes when the java.sql module is present.

Instantiation without no-args constructors

Can create instances of classes lacking a no-args constructor using Unsafe when available, with an option to disable it.

Java module system support

Ships a JPMS module descriptor (com.google.gson) so Java 9+ projects can use it as a named module.

Protobuf message JSON conversion

An optional proto module offers a JSON serializer and deserializer for Protocol Buffers messages.

Shrinker and native-image compatibility

Includes ProGuard/R8 guidance and tests plus GraalVM Native Image tests to support shrunken and native builds.

Static quality signals

Possible problems found without running the code.

276signals found
0high severity
26confirmed by the analysis
250need a human to check
KindSignalWhereSeverity
StructureFunction has no callers in the callgraph
`RawCollectionsExample.main` is parsed as code and calls 1 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/extras/examples/rawcollections/RawCollectionsExample.java:41medium
StructureFunction has no callers in the callgraph
`RuntimeTypeAdapterFactory.recognizeSubtypes` is parsed as code and calls 1 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java:206medium
StructureFunction has no callers in the callgraph
`RuntimeTypeAdapterFactory.create` is parsed as code and calls 1 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java:243medium
StructureFunction has no callers in the callgraph
`RuntimeTypeAdapterFactory.read` is parsed as code and calls 7 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java:265medium
StructureFunction has no callers in the callgraph
`RuntimeTypeAdapterFactory.write` is parsed as code and calls 7 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/typeadapters/RuntimeTypeAdapterFactory.java:296medium
StructureFunction has no callers in the callgraph
`UtcDateTypeAdapter.write` is parsed as code and calls 1 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java:36medium
StructureFunction has no callers in the callgraph
`UtcDateTypeAdapter.read` is parsed as code and calls 1 function(s), but no parsed code calls it.
extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java:46medium
StructureFunction has no callers in the callgraph
`InterceptorTest.setUp` is parsed as code and calls 1 function(s), but no parsed code calls it.
extras/src/test/java/com/google/gson/interceptors/InterceptorTest.java:47medium
Call graphFunction calls itself
`com_google_gson_TypeAdapter_NullSafeTypeAdapter_read_java_lang_Object_com_google_gson_stream_JsonReader_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_TypeAdapter_NullSafeTypeAdapter_write_void_com_google_gson_stream_JsonWriter_java_lang_Object_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_internal_GsonTypes_canonicalize_java_lang_reflect_Type_java_lang_reflect_Type_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_internal_GsonTypes_equals_boolean_java_lang_reflect_Type_java_lang_reflect_Type_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_internal_GsonTypes_getGenericSupertype_java_lang_reflect_Type_java_lang_reflect_Type_java_lang_Class_java_lang_Class_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_internal_GsonTypes_getRawType_java_lang_Class_java_lang_reflect_Type_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_internal_GsonTypes_resolve_java_lang_reflect_Type_java_lang_reflect_Type_java_lang_Class_java_lang_reflect_Type_java_util_Map_` has a direct self-call in the static callgraph.
medium
Call graphFunction calls itself
`com_google_gson_internal_LinkedTreeMap_removeInternal_void_com_google_gson_internal_LinkedTreeMap_Node_boolean_` has a direct self-call in the static callgraph.
medium

A sample of the highest-ranked signals. These come from static analysis: they are leads to review, not confirmed bugs.

Unused functions

Functions nothing in the repository calls.

4 functions have no caller in the call graph. They may be public API, called dynamically, or dead code.

FunctionLocationLines
C.Cgson/src/test/java/com/google/gson/functional/JsonAdapterAnnotationOnClassesTest.java:2455
RuntimeTypeAdapterFactoryFunctionalTest.ofgson/src/test/java/com/google/gson/functional/RuntimeTypeAdapterFactoryFunctionalTest.java:1149
RuntimeTypeAdapterFactoryFunctionalTest.ofgson/src/test/java/com/google/gson/functional/RuntimeTypeAdapterFactoryFunctionalTest.java:1229
MyClass.MyClassgson/src/test/java/com/google/gson/functional/SerializedNameTest.java:586

Recent changes

What changed in the last 30 days, in plain language.

Gson daily change summary (google/gson, 19 commits by 5 authors in the window; the payload shows details for the first four commits and part of the fifth, so this covers only those)

1. Standardizing the project name to "Gson" (881d2b5, Marcono1234, #3150)

  • Replaced "GSON" with "Gson" across 8 files, with 5 hunks in Gson.java.
  • User-visible runtime messages changed.
  • Gson.getAdapter now throws IllegalArgumentException("Gson (<version>) cannot handle <type>").
  • Gson.getDelegateAdapter now throws "Gson cannot serialize or deserialize <type>".
  • The AssertionError wrappers in Gson.toJson (two overloads) and Gson.fromJson now read "AssertionError (Gson <version>): ...".
  • Anyone matching these messages as strings, such as log scrapers or tests, will see different text.
  • GsonVersionDiagnosticsTest was updated to match: its regex is now \(Gson \d\.\d+\.\d...\), and the sample strings and the indexOf("(Gson") check were changed too.
  • The other edits are comments and Javadoc only:
  • RuntimeTypeAdapterFactory
  • MapTypeAdapterFactory
  • Streams (now says "JsonElement trees")
  • TypeAdapters (a comment about compatibility with Gson 1.7)
  • ProtoTypeAdapter
  • FieldExclusionTest
  • The impact tooling rates this "High impact" (score 100) because it touches Gson.java. Every changed function is labelled low risk, and the only behavioral change is the message text.

2. Comment typo fix (094f500, Marcono1234, #3148)

  • Two comments said "compatibility with JSON 1.5 and earlier". They now say "Gson 1.5", in Gson.fromJson and Streams.parse.
  • There is no logic change. Streams.parse is flagged high risk (47 impacted callers across 12 files) only because of how widely it is used.

3. Build and tooling changes (Éamonn McManus)

  • 66dd98a (#3152): In the root pom.xml, the disable-spotless profile now applies to JDKs before 21 instead of before 17. The Spotless formatting plugin therefore only runs on Java 21 or later.
  • 828cbe0 (#3153): In proto/pom.xml, protobuf-maven-plugin went from 5.1.8 to 5.1.11.

4. Release 2.15.0 (fcd4169, Éamonn McManus, maven-release-plugin)

  • This is the "prepare release gson-parent-2.15.0" commit and it touches 11 files. The payload is cut off partway through, so I only saw some of them.
  • README.md and UserGuide.md now show 2.15.0 in the Gradle and Maven snippets, replacing 2.14.0.
  • extras/pom.xml moves from 2.14.1-SNAPSHOT to 2.15.0, including the parent and the gson dependency. Its reproducible-build timestamp is now 2026-10-24T01:05:45Z, and its SCM tag is gson-parent-2.15.0.
  • gson/pom.xml has parent-version edits that were cut off in the payload.

Overall: Gson 2.15.0 was prepared for release on 2026-10-24. The code changes in the window are the "Gson" naming cleanup, which also changes some exception message text, and one comment typo fix. The rest is build maintenance: the Spotless JDK threshold, a protobuf plugin bump and the release version changes.

Ask about this repository

An example question, answered from the code.

What does this project do and how is it organised?

Question Summary

The user asks what this project does and how the repository is organised.

Direct Answer

  • [MARKUP] The project is Gson, a Java library that converts Java objects to JSON. README.md:6 says that other tools usually need annotations in your classes, which you can't add without source access, and often don't fully support Java Generics. It names both as important Gson design goals. UserGuide.md:67 says it was created for use inside Google and is now used by public projects and companies.
  • [MARKUP] It is a Maven multi-module build. The root pom.xml, gson/pom.xml, extras/pom.xml and test-shrinker/pom.xml all appear in the evidence.
  • [MARKUP] The core library lives under gson/src/main/java/com/google/gson/, for example internal/GsonTypes.java. Its tests live under gson/src/test/java/com/google/gson/, with functional tests in a functional/ subfolder.
  • [UNKNOWN/derived] Stored summaries also list proto/ and test-graal-native-image/ modules. The supplied source evidence does not show these directly, so treat them as unconfirmed.

Details

What it does

  • [MARKUP] README.md:6 is the only direct statement of purpose: Java object to JSON conversion, working on classes you don't own, and generics support.
  • [MARKUP] The tests show the kinds of behaviour covered:
  • JsonPrimitiveTest (gson/src/test/java/com/google/gson/JsonPrimitiveTest.java) checks JsonPrimitive equality and hash codes across number types. testEqualsAcrossTypes shows that JsonPrimitive("a") equals JsonPrimitive('a'), and that the numeric types BigInteger, int, long, BigDecimal and Float.NaN/Double.NaN compare equal across types. testEqualsDoesNotEquateStringAndNonStringTypes shows that JsonPrimitive("true"), "0" and "NaN" do not equal the boolean, integer and float primitives.
  • ExclusionStrategyFunctionalTest covers exclusion strategies.
  • CustomTypeAdaptersTest and GsonTypeAdapterTest cover custom type adapters.
  • MixedStreamTest has tests named testReadDoesNotMutateState and testWriteDoesNotMutateState.
  • ReflectionAccessFilterTest includes the message "ReflectionAccessFilter does not permit using reflection for class java.io.Reader".
  • [GRAPH] GsonTypes.newParameterizedTypeWithOwner (gson/src/main/java/com/google/gson/internal/GsonTypes.java:48-59) is the one production function shown. Its callers are GsonTypes.resolve, TypeToken.getParameterized, and several tests (GenericArrayTypeTest.setUp, GsonTypesTest.*, MapTest.testCustomSerializerForSpecificMapType, ParameterizedTypeTest.setUp). The graph shows no callees, and the function body is not included. Its callers are consistent with the generics support described in README.md:6.

How it is organised

  • [MARKUP] pom.xml at the root and a pom.xml in each of gson/, extras/ and test-shrinker/. A comment in test-shrinker/pom.xml:157 says R8 runs as a standalone JAR and doesn't need any of the project classes.
  • [MARKUP] Documentation files README.md and UserGuide.md sit at the root.
  • [MARKUP] Within gson/, production code is under src/main/java/com/google/gson/ (with an internal package), and tests are under src/test/java/com/google/gson/.
  • [SEMANTIC/derived] The stored summaries describe extras/ as supplementary features and test-shrinker/ as shrinker tests (R8/ProGuard). They also describe the core classes Gson, GsonBuilder, JsonElement, JsonPrimitive, TypeToken, JsonReader and JsonWriter. Treat these as derived context. Only JsonPrimitive, TypeToken and GsonTypes are corroborated by the source snippets.

Gaps

  • The evidence does not include the directory tree, the Gson or GsonBuilder source, or the module list from the root pom.xml. Module responsibilities beyond gson/ are therefore not directly confirmed.

Security review

An AI review of how outside input reaches risky operations.

No exploitable findings.

This repository is Gson, a JSON serialization library. It has no network service, no authentication, no agent or tool execution, no handling of credentials, and no file-system operations that take paths from JSON input. Its only entry points are benchmark and example main() methods. I checked the flagged sinks and none of them can be driven by untrusted input. (1) Every Class.forName call in main code uses a hard-coded literal: sun.misc.Unsafe, java.lang.reflect.RecordComponent, java.sql.Date and com.google.gson.internal.bind.JavaTimeTypeAdapters. JSON data never chooses which class gets loaded. (2) Deserialization picks its target type from the developer-supplied Type/TypeToken, not from the JSON. Polymorphic deserialization in extras (RuntimeTypeAdapterFactory.create/read) looks the type label up in the developer-registered labelToDelegate map and throws JsonParseException for unknown labels, so it is an allowlist and cannot be used as a gadget chain. (3) LazilyParsedNumber.readObject and LinkedTreeMap.readObject are Java-serialization guards that throw InvalidObjectException. They are not sinks. (4) The 'file write/delete' and 'network' matches (JsonArray.remove, LinkedTreeMap.remove, JsonTreeWriter.endArray, TypeAdapters.read) are false positives: they only change in-memory collections or JSON trees. UnsafeAllocator does build objects without calling a constructor, but only for the type the application asked for, and ReflectionAccessFilter can limit it. That is an application-level design choice, not a path to code execution, file access or credential theft. No attack chain meets the catastrophic threshold.