Moshi Documentation

Add moshi-adapters to your project to access prebuilt JsonAdapters for common types like Rfc3339DateJsonAdapter for java.util.Date.

<!-- Maven -->
<dependency>
  <groupId>com.squareup.moshi</groupId>
  <artifactId>moshi-adapters</artifactId>
  <version>latest.version</version>
</dependency>

<!-- Gradle -->
implementation 'com.squareup.moshi:moshi-adapters:latest.version'

To use Moshi with Kotlin classes via reflection, you must add the moshi-kotlin dependency and register the KotlinJsonAdapterFactory.

Note: The reflection adapter requires the kotlin-reflect library. For better performance and to avoid the kotlin-reflect dependency, use Codegen instead.

1. Add dependency:

implementation("com.squareup.moshi:moshi-kotlin:1.15.2")

2. Register factory:

val moshi = Moshi.Builder()
    .addLast(KotlinJsonAdapterFactory())
    .build()

To use Moshi in your project, add the dependency via Maven or Gradle.

Maven

<dependency>
  <groupId>com.squareup.moshi</groupId>
  <artifactId>moshi</artifactId>
  <version>1.15.2</version>
</dependency>

Gradle

implementation("com.squareup.moshi:moshi:1.15.2")

Use Moshi.Builder to create a Moshi instance, then obtain a JsonAdapter for your target class to perform JSON operations.

Parsing JSON to an object:

String json = ...;
Moshi moshi = new Moshi.Builder().build();
JsonAdapter<BlackjackHand> jsonAdapter = moshi.adapter(BlackjackHand.class);
BlackjackHand blackjackHand = jsonAdapter.fromJson(json);

Serializing an object to JSON:

BlackjackHand blackjackHand = ...;
Moshi moshi = new Moshi.Builder().build();
JsonAdapter<BlackjackHand> jsonAdapter = moshi.adapter(BlackjackHand.class);
String json = jsonAdapter.toJson(blackjackHand);

String json = ...;

Moshi moshi = new Moshi.Builder().build();
JsonAdapter<BlackjackHand> jsonAdapter = moshi.adapter(BlackjackHand.class);

BlackjackHand blackjackHand = jsonAdapter.fromJson(json);
System.out.println(blackjackHand);

Use Moshi.Builder to create a Moshi instance. For Kotlin, it is recommended to use either Kotlin code generation or the KotlinJsonAdapterFactory for reflection.

Parsing JSON to an object:

val json: String = ...
val moshi: Moshi = Moshi.Builder().build()
val jsonAdapter: JsonAdapter<BlackjackHand> = moshi.adapter<BlackjackHand>()
val blackjackHand = jsonAdapter.fromJson(json)

Serializing an object to JSON:

val blackjackHand = ...
val moshi: Moshi = Moshi.Builder().build()
val jsonAdapter: JsonAdapter<BlackjackHand> = moshi.adapter<BlackjackHand>()
val json: String = jsonAdapter.toJson(blackjackHand)

val json: String = ...

val moshi: Moshi = Moshi.Builder().build()
val jsonAdapter: JsonAdapter<BlackjackHand> = moshi.adapter<BlackjackHand>()

val blackjackHand = jsonAdapter.fromJson(json)
println(blackjackHand)

Use @JsonQualifier to apply a specific type adapter to certain fields of a type without changing the encoding for all instances of that type. This is useful when the same type (e.g., Int) needs different JSON representations (e.g., a decimal number vs. a hex color string).

1. Define the qualifier:

@Retention(RUNTIME)
@JsonQualifier
annotation class HexColor

2. Apply to the field:

class Rectangle(
  val width: Int,
  val height: Int,
  @HexColor val color: Int
)

3. Create the adapter using the qualifier:

class ColorAdapter {
  @ToJson fun toJson(@HexColor rgb: Int): String {
    return "#%06x".format(rgb)
  }

  @FromJson @HexColor fun fromJson(rgb: String): Int {
    return rgb.substring(1).toInt(16)
  }
}

4. Register the adapter:

val moshi = Moshi.Builder()
    .add(ColorAdapter())
    .build()

Moshi's Kotlin codegen uses Kotlin Symbol Processing (KSP) to generate fast, compile-time adapters for your classes. This is preferred over reflection.

1. Annotate your classes:

@JsonClass(generateAdapter = true)
data class BlackjackHand(
  val hidden_card: Card,
  val visible_cards: List<Card>
)

2. Configure KSP in your build file:

plugins {
  id("com.google.devtools.ksp") version "2.3.4" // Or latest
}

dependencies {
  ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.2")
}

If you are using reflective serialization with R8 or ProGuard, you must add keep rules for your serialized classes.

For Enums, annotate them with @JsonClass(generateAdapter = false) to prevent them from being removed or obfuscated by R8/ProGuard.

@JsonClass(generateAdapter = false)
enum class Suit {
  CLUBS, DIAMONDS, HEARTS, SPADES
}

To use a prebuilt adapter, supply an instance of the desired adapter to the Moshi.Builder using the .add(Class, JsonAdapter) method before calling .build().

Moshi moshi = new Moshi.Builder()
    .add(Date.class, new Rfc3339DateJsonAdapter())
    //etc
    .build();

To prevent a field from being included in JSON during serialization or being read from JSON during deserialization, annotate it with @Json(ignore = true).

In Kotlin, ignored fields in a primary constructor must have a default value.

class BlackjackHand(
  @Json(ignore = true) var total: Int = 0,
  val hidden_card: Card,
  val visible_cards: List<Card>
)