Moshi
Modern JSON serialization library for Android and Java/Kotlin, built by Square as a successor to Gson. Moshi handles Kotlin data classes correctly (null safety, default values, non-null enforcement), uses KSP/kapt code generation for type adapters, and supports polymorphic JSON with JsonClass. Used as the recommended JSON serializer for Retrofit on Android, especially for Kotlin codebases.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Serialization library — no network exposure. Square maintains. JSON parsing hardened against malformed input. No credential handling.
⚡ Reliability
Best When
You're using Retrofit on Android with a Kotlin codebase and want correct null-safety enforcement and compile-time JSON adapter generation.
Avoid When
You're building Kotlin Multiplatform — use kotlinx.serialization instead as it supports all KMP targets natively.
Use Cases
- • Serialize/deserialize JSON for agent API responses in Android and JVM applications with correct Kotlin null safety enforcement
- • Use Moshi with Retrofit (via converter-moshi) for type-safe Android HTTP client JSON parsing in agent networking code
- • Define polymorphic JSON models for agent message types using Moshi's PolymorphicJsonAdapterFactory for discriminated union patterns
- • Generate efficient JSON adapters at compile time with @JsonClass(generateAdapter = true) to avoid reflection overhead in agent code
- • Write custom Moshi adapters for complex agent data types (timestamps, enums, money) that need custom serialization logic
Not For
- • Pure Java projects — Gson has better Java ergonomics; Moshi's Kotlin code generation requires Kotlin
- • Complex nested polymorphism with many subtypes — kotlinx.serialization's sealed class support is more ergonomic for complex hierarchies
- • Cross-platform serialization — use kotlinx.serialization for Kotlin Multiplatform (Android + iOS + JS)
Interface
Authentication
Serialization library — no authentication. No network calls.
Pricing
Square open source library. Apache 2.0 license.
Agent Metadata
Known Gotchas
- ⚠ Moshi requires @JsonClass(generateAdapter = true) on data classes for code-gen — without it, Moshi falls back to reflection which is slower and misses Kotlin null safety
- ⚠ Default parameter values in Kotlin data classes are NOT respected by Moshi without @JsonClass code gen — reflection mode ignores defaults and sets fields to null
- ⚠ Moshi does not support Kotlin sealed classes out of the box — use PolymorphicJsonAdapterFactory explicitly or moshi-sealed extension library for sealed class hierarchies
- ⚠ Moshi 1.14+ requires Java 8 or higher — older Android minSdk targets may need desugaring or staying on 1.13
- ⚠ Adding Moshi adapter to Retrofit requires converter-moshi dependency AND creating Moshi with all required adapters registered — forgetting KotlinJsonAdapterFactory breaks Kotlin data classes in reflection mode
- ⚠ Moshi's JsonAdapter is not thread-safe if custom adapters maintain state — always create new adapter instances or use a thread-local pattern for stateful custom adapters
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Moshi.
Scores are editorial opinions as of 2026-03-06.