google/gson
68.6
Adequate · 13 November 2026
21.6k
lines of production code
Java
primary language
8
measurements over time
What this system is
Features
Add Gson micro-benchmarks for serialization and deserialization
The metrics module now includes Caliper-based micro-benchmarks to measure Gson performance. This adds benchmarks for serializing and deserializing a \BagOfPrimitives\ object, deserializing collections of these objects, and parsing JSON documents (including Twitter feed data) using both Gson and Jackson APIs. A helper runner is provided to execute these benchmarks locally without uploading results.
metrics/src · high confidence
Add ISO-8601 date parsing and formatting utilities
Gson now includes a dedicated utility class, ISO8601Utils, for parsing and formatting dates in ISO-8601 format. This implementation, adapted from Jackson Databind, provides faster and more garbage-collection-friendly date handling than standard SimpleDateFormat. It supports a wide range of ISO-8601 patterns, including date-only, date-time with optional milliseconds, and various timezone representations (UTC 'Z' or offset '+/-hh:mm'). This change improves the reliability and performance of date serialization and deserialization within Gson.
gson/src/main/java/com/google/gson/internal/bind/util · high confidence
Add support for java.sql.Date, Time, and Timestamp serialization
Gson now includes built-in adapters for java.sql.Date, java.sql.Time, and java.sql.Timestamp, allowing these types to be serialized and deserialized automatically. The implementation ensures thread safety by synchronizing access to the underlying DateFormat instances and correctly restores the original time zone after parsing. Support for these types is optional and gracefully disabled if the java.sql module is not present in the runtime environment.
gson/src/main/java/com/google/gson/internal/sql · high confidence
Added default ProGuard/R8 rules for code shrinking
Gson now includes a default \gson.pro\ file in \META-INF\ that is automatically recognized by ProGuard and R8. This file provides additive rules to preserve generic signatures, Gson annotations, \TypeToken\ classes, and fields annotated with \@SerializedName\, ensuring correct behavior when applications use code shrinking or obfuscation. The previous \assembly-descriptor.xml\ file used for packaging has been removed.
gson/src/main/resources · high confidence
Added example for serializing raw collections
A new example file, RawCollectionsExample.java, has been added to the extras module to demonstrate how to serialize and deserialize raw Java collections using Gson. This example shows how to handle a raw Collection containing mixed types (Strings, Integers, and custom objects) and how to parse the resulting JSON back into specific types.
extras/src/main/java/com/google/gson/extras · high confidence
Adds JPMS module descriptor for Gson
Gson now includes a module-info.java file, defining the module com.google.gson and exporting its core packages (com.google.gson, com.google.gson.annotations, com.google.gson.reflect, com.google.gson.stream). This enables the library to be used within Java Platform Module System (JPMS) applications, with optional static dependencies on java.sql and jdk.unsupported to support specific serialization features without breaking builds on minimal JDKs.
gson/src/main/java · high confidence
Gson version information now accessible at runtime
The internal build configuration class has been replaced with a new public \GsonBuildConfig\ class that exposes the current Gson version via a static \VERSION\ field. This allows applications to programmatically retrieve the library version at runtime, which is particularly useful for debugging and logging when errors occur. The previous internal \NullExclusionStrategy\ class has been removed as part of this change.
gson/src/main/java-templates · high confidence
Introduce streaming JSON reader and writer with strictness and nesting controls
The \gson/src/main/java/com/google/gson/stream\ package now provides the core streaming JSON API (\JsonReader\ and \JsonWriter\) along with supporting types (\JsonToken\, \JsonScope\, \MalformedJsonException\). Users can now parse and generate JSON streams with configurable strictness (defaulting to \LEGACY\_STRICT\) and a default nesting limit to prevent stack overflow on deeply nested structures. The \JsonWriter\ supports formatting styles and null serialization controls, while \JsonReader\ includes features like unpaired surrogate rejection in strict mode and location tracking for error reporting.
gson/src/main/java/com/google/gson/stream · high confidence
New @JsonAdapter annotation and enhanced field versioning/exposure controls
Gson now supports the new @JsonAdapter annotation, allowing users to specify a custom TypeAdapter, TypeAdapterFactory, or JsonSerializer/JsonDeserializer directly on classes or fields to control serialization and deserialization logic. Additionally, the @SerializedName annotation now accepts an 'alternate' attribute, enabling fields to be deserialized from multiple JSON property names. The @Expose annotation has been extended with 'serialize' and 'deserialize' boolean attributes, giving finer control over which operations a field participates in. Finally, the new @Until annotation complements @Since, allowing users to exclude fields from JSON output for versions greater than or equal to a specified threshold, supporting more granular API versioning strategies.
gson/src/main/java/com/google/gson/annotations · high confidence
New extras type adapters for runtime polymorphism, UTC dates, and PostConstruct initialization
The extras module now includes three new type adapters: RuntimeTypeAdapterFactory enables serialization and deserialization of polymorphic object hierarchies by embedding and recognizing a configurable type field; UtcDateTypeAdapter provides strict UTC ISO-8601 date formatting and parsing using a Jackson-derived parser for better compatibility; and PostConstructAdapterFactory automatically invokes methods annotated with javax.annotation.PostConstruct after deserializing objects.
extras/src/main/java/com/google/gson/typeadapters · high confidence
New formatting, streaming, and reflection control APIs
Gson introduces several new capabilities for controlling serialization output and runtime behavior. Users can now customize the appearance of pretty-printed JSON via the new \FormattingStyle\ class, allowing configuration of newlines, indentation, and spacing after separators. A new \JsonStreamParser\ class enables asynchronous reading of multiple JSON elements from a stream. Additionally, a \ReflectionAccessFilter\ interface allows users to block reflective access to specific classes, which is particularly useful for managing Java Platform Module System (JPMS) restrictions or preventing access to non-model classes.
gson/src/main/java/com/google/gson · high confidence
New protocol buffer serialization adapters and migration aid
The proto module now includes three new components to handle Protocol Buffers in Gson. ProtoTypeAdapter provides a configurable serializer/deserializer that supports custom field name formats, explicit json\_name field options, and enum serialization by name or number. LegacyProtoTypeAdapterFactory is added as a migration aid to replicate Gson's previous, fragile reflection-based behavior for existing users, with a recommendation to migrate to the new adapter. StructTypeAdapter offers direct conversion between protobuf Struct and Gson JsonObject without intermediate string parsing.
proto/src/main · high confidence
Repository initialization with comprehensive documentation and build configuration
The repository is initialized with the full project structure, including the Apache 2.0 license, a detailed README specifying Java 8+ and Android API 24+ requirements, and a complete user guide. A comprehensive changelog is included, documenting features and fixes from version 2.3.1 through 2.10, such as Java record support and TypeToken overloads. The project also introduces a formal release process, a troubleshooting guide for common issues like ProGuard configuration, and a design document explaining Gson's architectural decisions. Build tooling is standardized on Maven with JDK 17+ required for building, and Git hygiene is improved with a .gitignore and .git-blame-ignore-revs file to handle formatting and line-ending changes.
(repo-wide) · high confidence
Removals
Removal of JavaCC-based JSON parser
The JavaCC grammar definition file (JsonParser.jj) and its generated parser classes have been removed from the codebase. This eliminates the legacy JavaCC-based JSON parsing implementation, which previously handled tokenization and parsing of JSON structures including numbers, strings, and objects.
gson/src/main/javacc · high confidence
Architecture
Refactored internal type adapters into dedicated classes in com.google.gson.internal.bind
The internal binding logic for core types has been reorganized into specific, dedicated adapter classes within the \com.google.gson.internal.bind\ package. This change introduces distinct implementations for arrays (\ArrayTypeAdapter\), collections (\CollectionTypeAdapterFactory\), maps (\MapTypeAdapterFactory\), enums (\EnumTypeAdapter\), and JSON elements (\JsonElementTypeAdapter\), alongside updated streaming readers and writers (\JsonTreeReader\, \JsonTreeWriter\). By decoupling these responsibilities from the monolithic \ReflectiveTypeAdapterFactory\ and \DefaultTypeAdapters\, Gson now uses specialized factories for each type category, improving code modularity and maintainability while preserving existing serialization and deserialization behavior.
gson/src/main/java/com/google/gson/internal/bind · high confidence
Behavioural changes
Configure JVM flags for Error Prone compatibility
Added a new \.mvn/jvm.config\ file to specify JVM arguments required for Error Prone. This ensures the build process can access internal JDK compiler APIs via \--add-exports\ and \--add-opens\, preventing potential runtime errors or warnings during compilation.
.mvn · high confidence
Improved error messages and Java Record support in reflection handling
The internal reflection helper now provides more descriptive error messages when serialization fails due to inaccessible constructors or fields, including links to a troubleshooting guide for common module-access issues. Additionally, the library now supports Java Records by dynamically detecting their availability at runtime and delegating to specific helper implementations, allowing Gson to correctly serialize and deserialize record types when running on compatible JVMs.
gson/src/main/java/com/google/gson/internal/reflect · high confidence
Internal refactoring and Java 9+ compatibility improvements
This update refactors the internal implementation classes to improve compatibility with modern Java versions and enhance security. The \ConstructorConstructor\ now supports instance creators registered with raw types and integrates with \ReflectionAccessFilter\ to control unsafe instantiation. \Excluder\ has been restructured as a \TypeAdapterFactory\ to better handle serialization exclusions. \LazilyParsedNumber\ now implements \Comparable\ and \equals\/\hashCode\, and deserialization is restricted to prevent security issues. \LinkedTreeMap\ is introduced as an ordered map implementation. Additionally, \PreJava9DateFormatProvider\ ensures consistent date formatting across Java versions, and \NumberLimits\ enforces constraints on parsed numbers to prevent performance issues.
gson/src/main/java/com/google/gson/internal · high confidence
Move interceptor support from alpha to extras
The interceptor functionality, previously available in the alpha module, has been moved to the extras module. This change includes the relocation and renaming of the \JsonPostDeserializer\ interface (from \JsonSerializationContextDefault\) and the introduction of the \@Intercept\ annotation and \InterceptorFactory\ type adapter factory, allowing users to define post-deserialization logic for their classes.
extras/src/main/java/com/google/gson/interceptors · high confidence
TypeToken now prevents capturing type variables and enforces canonical type representation
The TypeToken class in the reflect package now throws an IllegalArgumentException if an anonymous subclass attempts to capture a type variable (e.g., TypeToken\<List\<T\>\>), preventing false sense of type-safety and potential runtime ClassCastExceptions. Additionally, TypeToken now uses GsonTypes.canonicalize to ensure type arguments are in a canonical form, improving consistency and correctness for generic type resolution. The class also validates that direct subclasses are used, throwing an IllegalStateException for raw TypeToken usage or indirect subclasses, and caches the hashCode for performance.
gson/src/main/java/com/google/gson/reflect · high confidence
Test coverage
Add integration tests for Gson behavior under code shrinking and obfuscation; Added JPMS integration tests to verify module descriptor and reflection behavior; Added ProGuard configuration for Gson test cases; Added comprehensive tests for TypeToken reflection utilities; Added functional tests for circular references, concurrency, custom serializers/deserializers, delegate adapters, enums, and exclusion strategies; Added functional tests for protobuf serialization features; Added integration test for OSGi manifest attributes; Added integration tests for Gson with GraalVM Native Image; Added performance benchmark tests for Gson serialization and deserialization; Added protobuf test schemas for serialization validation; Added test coverage for Gson core components; Added tests for JsonReader path tracking and strictness modes; Added tests for PostConstruct, RuntimeTypeAdapter, and UTC Date adapters; Added tests for SQL type serialization and support; Added unit tests for Gson interceptors; Added unit tests for ISO8601Utils date parsing and formatting; Added unit tests for internal Gson components; Expanded test coverage for date adapters, JSON tree readers/writers, and Java 17 record support; Updated test utilities and test data types.
Dependencies
Maven project structure reorganized into multi-module build
The Gson build has been restructured from a single-module project into a multi-module Maven setup. A new root \gson-parent\ POM now manages the build, introducing dedicated submodules for \gson-extras\ (utility type adapters), \gson-metrics\ (performance benchmarks), \gson-proto\ (Protocol Buffers support), and integration test modules for JPMS, GraalVM Native Image, and code shrinking (ProGuard/R8). The core \gson\ module now inherits from this parent, and the build enforces JDK 17+ for compilation while maintaining Java 8 as the target release version.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 66 → 69 (+2.8)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.3) — scores are not directly comparable.
Lenses
- Code Health 69 → 69 (+0.1)
- Architecture 99 → 99 (+0.1)
- Maturity 59 → 65 (+5.9)
- Readiness 67 → 67 (+0.1)
- Security 81 → 81 (+0.0)
Resolved (33)
- Ambiguous redundancy. While the parameter types differ (Class vs Type), the method name get is overloaded in a way that often leads to confusion with TypeToken's primary purpose of capturing generic types. More critically, TypeToken has a constructor that takes a Type, and static factory methods that do similar things. However, the most glaring inconsistency is between TypeToken.get(Class) and TypeToken.get(Type) which return different generic bounds (T vs ?) for conceptually similar 'creation' operations, whereas TypeToken is typically instantiated via constructor. A more consistent API would likely unify creation or use distinct names like forClass and forType.
- Duplicate operation with different names. parse and parseReader perform the exact same function (parsing a JsonReader into a JsonElement).
- Duplicate operation with different names. parse and parseReader perform the exact same function (parsing a Reader into a JsonElement).
- Duplicate operation with different names. parse and parseString perform the exact same function (parsing a String into a JsonElement).
- Duplicated block (10 lines × 2) (extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java)
- Duplicated block (11 lines × 2) (extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java)
- Duplicated block (11 lines × 2) (metrics/src/main/java/com/google/gson/metrics/BagOfPrimitivesDeserializationBenchmark.java)
- Inconsistent parameter types for equivalent operations. TypeToken<T> is essentially a wrapper around Type (specifically Type that captures generic type arguments). Passing a TypeToken vs a raw Type to fromJson results in different runtime behavior (generic type capture vs raw type), but the method names are identical. This forces users to understand the subtle difference between Type and TypeToken to choose the correct overload, which is a common source of error.
- Near-duplicate member pair (33 shared lines) (extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java)
- No ADRs found
- No assertions: testCollectionOfEnumsDeserialization (gson/src/test/java/com/google/gson/functional/EnumTest.java)
- No assertions: testCustomCollectionCreation (gson/src/test/java/com/google/gson/internal/ConstructorConstructorTest.java)
- No assertions: testCustomMapCreation (gson/src/test/java/com/google/gson/internal/ConstructorConstructorTest.java)
- No assertions: testDateSerializationWithDateStyle (gson/src/test/java/com/google/gson/functional/DefaultTypeAdaptersTest.java)
- No assertions: testDefaultSqlDateDeserialization (gson/src/test/java/com/google/gson/internal/sql/SqlTypesGsonTest.java)
- No assertions: testDefaultSqlTimeDeserialization (gson/src/test/java/com/google/gson/internal/sql/SqlTypesGsonTest.java)
- No assertions: testDefaultSqlTimestampDeserialization (gson/src/test/java/com/google/gson/internal/sql/SqlTypesGsonTest.java)
- No assertions: testEqualsAcrossTypes (gson/src/test/java/com/google/gson/JsonPrimitiveTest.java)
- No assertions: testEqualsAndHashCode (gson/src/test/java/com/google/gson/internal/LinkedTreeMapTest.java)
- No assertions: testEqualsAndHashCodeAcrossNumberTypes (gson/src/test/java/com/google/gson/JsonPrimitiveTest.java)
- …and 13 more
New (31)
- Edited copies of one member (3 members, 19+ corresponding lines) (test-shrinker/src/main/java/com/example/Main.java)
- Edited copies of one member (3 members, 20+ corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/JdkOptionalTypeAdapters.java)
- Edited copies of one member (3 members, 22+ corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/JsonTreeReader.java)
- Edited copies of one member (4 members, 22+ corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/JavaTimeTypeAdapters.java)
- Edited copies of one member (4 members, 39+ corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/JavaTimeTypeAdapters.java)
- Edited copies of one member (5 members, 13+ corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java)
- Edited copies of one member (6 members, 8+ corresponding lines) (test-shrinker/src/main/java/com/example/Main.java)
- Edited copy of a member (10 corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/NumberTypeAdapter.java)
- Edited copy of a member (11 corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/JsonTreeWriter.java)
- Edited copy of a member (11 corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java)
- Edited copy of a member (12 corresponding lines) (gson/src/main/java/com/google/gson/internal/reflect/ReflectionHelper.java)
- Edited copy of a member (13 corresponding lines) (gson/src/main/java/com/google/gson/stream/JsonReader.java)
- Edited copy of a member (19 corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java)
- Edited copy of a member (19 corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/TypeAdapters.java)
- Edited copy of a member (19 corresponding lines) (gson/src/main/java/com/google/gson/internal/sql/SqlDateTypeAdapter.java)
- Edited copy of a member (21 corresponding lines) (gson/src/main/java/com/google/gson/internal/bind/CollectionTypeAdapterFactory.java)
- Edited copy of a member (23 corresponding lines) (gson/src/main/java/com/google/gson/internal/LinkedTreeMap.java)
- Edited copy of a member (23 corresponding lines) (proto/src/main/java/com/google/gson/protobuf/LegacyProtoTypeAdapterFactory.java)
- Edited copy of a member (25 corresponding lines) (extras/src/main/java/com/google/gson/typeadapters/UtcDateTypeAdapter.java)
- Edited copy of a member (28 corresponding lines) (gson/src/main/java/com/google/gson/Gson.java)
- …and 11 more
Changes since last survey
- 12 commits — 11 feature/other, 1 fixes
By area
- gson/src — 5 commits
- (repo) — 4 commits
- (root) — 1 commit
- .github/workflows — 1 commit
- gson/pom.xml — 1 commit
Notable commits
- fix: Merge pull request #3157 from wozhenbang2004/fix/json-array-sublist-clear
- change: Add built-in TypeAdapterFactory support for java.util.Optional*
- change: Add tests for clearing sublists in JsonArrayTest clearing JsonArray sublist views
- change: Address review comment
- change: Address review comments
- change: Avoid quadratic clearing in JsonArray sublists
- change: Bump the github-actions group with 7 updates (#3159)
- change: Bump the maven group across 2 directories with 1 update
- change: Merge pull request #3155 from google/release
- change: Merge pull request #3161 from google/dependabot/maven/gson/maven-7667e75bf7
- change: Merge pull request #3162 from cushon/optional
- change: Merge pull request #3164 from google/dependabot/maven/maven-3b846bd855
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
google/gson was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 13 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit a961b0fe088f8558d00cc1b56e506a3656907a91 — the exact code this score is about.
- Scored under rubric-2026.11.3 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.61+preprod-f3449e6eb431.