How should Android teams prevent JSON field names from breaking when ProGuard or R8 obfuscation is enabled?

Why obfuscation breaks JSON field names in Android builds

Obfuscation tools rename classes, methods, and fields unless you explicitly preserve the members that serialization depends on. For JSON libraries such as GSON, that means the name used at runtime may no longer match the name that was written into the payload. The result is often silent data loss, missed reads, or version-to-version compatibility failures.

The core issue is not ProGuard or R8 themselves, it is that JSON serialization usually depends on stable member names. If those names change between builds, the app may still compile and ship cleanly, but deserialization can fail when an older object shape is read by a newer app build. That is why serialized model members need a retention rule, not just a code annotation.

For teams building on Android, the practical fix is to treat serialized model shape as part of the contract. If a field name must remain stable, preserve it with an annotation such as OWASP Cheat Sheet Series for implementation patterns around secure serialization and input handling, and pair that with explicit keep rules so shrinking does not rewrite the member names. When the wire format is already in production, the contract matters more than the source code symbol name.

Keeping serialization stable across versions

Using annotations such as SerializedName or Expose is effective only when the build rules respect them. The annotation tells the serializer what to use, but the shrinker still needs to be instructed not to remove or rename the field. In practice, Android teams should keep the members that form the external JSON contract and avoid relying on default reflection-based naming if the object will be persisted or exchanged between app versions.

This becomes especially important when JSON is stored locally, synced to a backend, or passed through work queues. In those cases, a renamed field can behave like a schema change even though no explicit migration was intended. If the object can outlive one app release, the team should assume that obfuscation is a compatibility risk, not a cosmetic build concern.

For broader serialization and app-hardening guidance, OWASP API Security Top 10 is useful for thinking about contract stability and broken object handling at the API boundary, while NIST Cybersecurity Framework 2.0 supports the governance side of preserving integrity in application data flows. Those references do not replace Android-specific keep rules, but they help teams treat serialization stability as a control objective.

Risk and Threat Considerations

When JSON field names change under obfuscation, the failure mode is usually integrity loss rather than a visible crash. That can surface as partial object reads, default values replacing real data, or old records becoming unreadable after an upgrade. In systems that depend on cached objects, offline data, or long-lived app state, the result can be corrupted user data and broken backward compatibility.

Failure mechanism: Shrinking or obfuscation renames a member that the serializer still expects by its original JSON key, so the app can no longer map payload fields to the intended model properties.

Impact: New builds may fail to read data written by earlier builds, and the breakage can remain hidden until a version upgrade, restore flow, or data migration path exposes it.

Practitioner Guidance

What to verify: Test a real upgrade path, not just a clean install. Serialize objects with one build, obfuscate a second build, and confirm the newer binary can still deserialize the earlier payload without defaulting fields or dropping values.

Common mistake: Teams often add an annotation and assume the problem is solved, but the serializer contract only stays stable if the shrinker rules preserve the annotated members as well. If either side changes, compatibility can still fail.

Decision rule: If the JSON object may cross a build boundary, preserve its field names deliberately and treat those members as part of the app’s data contract. If the object is purely internal and never serialized across versions, the retention requirement is less strict.

Practitioner takeaway: Obfuscation is safe only when the serialized shape is explicitly protected, so the control objective is stable wire compatibility, not just clean shrinking.

Related resources from NHI Mgmt Group

• How should teams prevent graph-RAG systems from breaking on long documents?
• How should security teams prevent path traversal issues when repository names are used to build filesystem paths?
• How should security teams prevent excessive file downloads in Google Drive without breaking normal collaboration?
• How should security teams implement data obfuscation in AWS environments to reduce exposure without breaking legitimate workflows?