Moshi

Moshi is a modern JSON library for Android and Java. It makes it easy to parse JSON into Java
objects:

String json = ...;

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

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

And it can just as easily serialize Java objects as JSON:

BlackjackHand blackjackHand = new BlackjackHand(
    new Card('6', SPADES),
    Arrays.asList(new Card('4', CLUBS), new Card('A', HEARTS)));

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

String json = jsonAdapter.toJson(blackjackHand);
System.out.println(json);

Built-in Type Adapters

Moshi has built-in support for reading and writing Java’s core data types:

Primitives (int, float, char...) and their boxed counterparts (Integer, Float, Character...).
Arrays, Collections, Lists, Sets, and Maps
Strings
Enums

It supports your model classes by writing them out field-by-field. In the example above Moshi uses
these classes:

class BlackjackHand {
  public final Card hidden_card;
  public final List<Card> visible_cards;
  ...
}

class Card {
  public final char rank;
  public final Suit suit;
  ...
}

enum Suit {
  CLUBS, DIAMONDS, HEARTS, SPADES;
}

to read and write this JSON:

{
  "hidden_card": {
    "rank": "6",
    "suit": "SPADES"
  },
  "visible_cards": [
    {
      "rank": "4",
      "suit": "CLUBS"
    },
    {
      "rank": "A",
      "suit": "HEARTS"
    }
  ]
}

The [Javadoc][javadoc] catalogs the complete Moshi API, which we explore below.

Custom Type Adapters

With Moshi, it’s particularly easy to customize how values are converted to and from JSON. A type
adapter is any class that has methods annotated @ToJson and @FromJson.

For example, Moshi’s default encoding of a playing card is verbose: the JSON defines the rank and
suit in separate fields: {"rank":"A","suit":"HEARTS"}. With a type adapter, we can change the
encoding to something more compact: "4H" for the four of hearts or "JD" for the jack of
diamonds:

class CardAdapter {
  @ToJson String toJson(Card card) {
    return card.rank + card.suit.name().substring(0, 1);
  }

  @FromJson Card fromJson(String card) {
    if (card.length() != 2) throw new JsonDataException("Unknown card: " + card);

    char rank = card.charAt(0);
    switch (card.charAt(1)) {
      case 'C': return new Card(rank, Suit.CLUBS);
      case 'D': return new Card(rank, Suit.DIAMONDS);
      case 'H': return new Card(rank, Suit.HEARTS);
      case 'S': return new Card(rank, Suit.SPADES);
      default: throw new JsonDataException("unknown suit: " + card);
    }
  }
}

Moshi moshi = new Moshi.Builder()
    .add(new CardAdapter())
    .build();

Voilà:

{
  "hidden_card": "6S",
  "visible_cards": [
    "4C",
    "AH"
  ]
}

Another example

Note that the method annotated with @FromJson does not need to take a String as an argument.
Rather it can take input of any type and Moshi will first parse the JSON to an object of that type
and then use the @FromJson method to produce the desired final value. Conversely, the method
annotated with @ToJson does not have to produce a String.

Assume, for example, that we have to parse a JSON in which the date and time of an event are
represented as two separate strings.

{
  "title": "Blackjack tournament",
  "begin_date": "20151010",
  "begin_time": "17:04"
}

We would like to combine these two fields into one string to facilitate the date parsing at a
later point. Also, we would like to have all variable names in CamelCase. Therefore, the Event
class we want Moshi to produce like this:

class Event {
  String title;
  String beginDateAndTime;
}

Instead of manually parsing the JSON line per line (which we could also do) we can have Moshi do the
transformation automatically. We simply define another class EventJson that directly corresponds
to the JSON structure:

class EventJson {
  String title;
  String begin_date;
  String begin_time;
}

And another class with the appropriate @FromJson and @ToJson methods that are telling Moshi how
to convert an EventJson to an Event and back. Now, whenever we are asking Moshi to parse a JSON
to an Event it will first parse it to an EventJson as an intermediate step. Conversely, to
serialize an Event Moshi will first create an EventJson object and then serialize that object as
usual.

class EventJsonAdapter {
  @FromJson Event eventFromJson(EventJson eventJson) {
    Event event = new Event();
    event.title = eventJson.title;
    event.beginDateAndTime = eventJson.begin_date + " " + eventJson.begin_time;
    return event;
  }

  @ToJson EventJson eventToJson(Event event) {
    EventJson json = new EventJson();
    json.title = event.title;
    json.begin_date = event.beginDateAndTime.substring(0, 8);
    json.begin_time = event.beginDateAndTime.substring(9, 14);
    return json;
  }
}

Again we register the adapter with Moshi.

Moshi moshi = new Moshi.Builder()
    .add(new EventJsonAdapter())
    .build();

We can now use Moshi to parse the JSON directly to an Event.

JsonAdapter<Event> jsonAdapter = moshi.adapter(Event.class);
Event event = jsonAdapter.fromJson(json);

Parse JSON Arrays

Say we have a JSON string of this structure:

[
  {
    "rank": "4",
    "suit": "CLUBS"
  },
  {
    "rank": "A",
    "suit": "HEARTS"
  }
]

We can now use Moshi to parse the JSON string into a List<Card>.

String cardsJsonResponse = ...;
Type type = Types.newParameterizedType(List.class, Card.class);
JsonAdapter<List<Card>> adapter = moshi.adapter(type);
List<Card> cards = adapter.fromJson(cardsJsonResponse);

Fails Gracefully

Automatic databinding almost feels like magic. But unlike the black magic that typically accompanies
reflection, Moshi is designed to help you out when things go wrong.

JsonDataException: Expected one of [CLUBS, DIAMONDS, HEARTS, SPADES] but was ANCHOR at path $.visible_cards[2].suit
  at com.squareup.moshi.JsonAdapters$11.fromJson(JsonAdapters.java:188)
  at com.squareup.moshi.JsonAdapters$11.fromJson(JsonAdapters.java:180)
	...

Moshi always throws a standard java.io.IOException if there is an error reading the JSON document,
or if it is malformed. It throws a JsonDataException if the JSON document is well-formed, but
doesn’t match the expected format.

Built on Okio

Moshi uses [Okio][okio] for simple and powerful I/O. It’s a fine complement to [OkHttp][okhttp],
which can share buffer segments for maximum efficiency.

Borrows from Gson

Moshi uses the same streaming and binding mechanisms as [Gson][gson]. If you’re a Gson user you’ll
find Moshi works similarly. If you try Moshi and don’t love it, you can even migrate to Gson without
much violence!

But the two libraries have a few important differences:

Moshi has fewer built-in type adapters. For example, you need to configure your own date
adapter. Most binding libraries will encode whatever you throw at them. Moshi refuses to
serialize platform types (java.*, javax.*, and android.*) without a user-provided type
adapter. This is intended to prevent you from accidentally locking yourself to a specific JDK or
Android release.
Moshi is less configurable. There’s no field naming strategy, versioning, instance creators,
or long serialization policy. Instead of naming a field visibleCards and using a policy class
to convert that to visible_cards, Moshi wants you to just name the field visible_cards as it
appears in the JSON.
Moshi doesn’t have a JsonElement model. Instead it just uses built-in types like List and
Map.
No HTML-safe escaping. Gson encodes = as \u003d by default so that it can be safely
encoded in HTML without additional escaping. Moshi encodes it naturally (as =) and assumes that
the HTML encoder – if there is one – will do its job.

Custom field names with @Json

Moshi works best when your JSON objects and Java objects have the same structure. But when they
don't, Moshi has annotations to customize data binding.

Use @Json to specify how Java fields map to JSON names. This is necessary when the JSON name
contains spaces or other characters that aren’t permitted in Java field names. For example, this
JSON has a field name containing a space:

{
  "username": "jesse",
  "lucky number": 32
}

With @Json its corresponding Java class is easy:

class Player {
  String username;
  @Json(name = "lucky number") int luckyNumber;

  ...
}

Because JSON field names are always defined with their Java fields, Moshi makes it easy to find
fields when navigating between Java and JSON.

Alternate type adapters with @JsonQualifier

Use @JsonQualifier to customize how a type is encoded for some fields without changing its
encoding everywhere. This works similarly to the qualifier annotations in dependency injection
tools like Dagger and Guice.

Here’s a JSON message with two integers and a color:

{
  "width": 1024,
  "height": 768,
  "color": "#ff0000"
}

By convention, Android programs also use int for colors:

class Rectangle {
  int width;
  int height;
  int color;
}

But if we encoded the above Java class as JSON, the color isn't encoded properly!

{
  "width": 1024,
  "height": 768,
  "color": 16711680
}

The fix is to define a qualifier annotation, itself annotated @JsonQualifier:

@Retention(RUNTIME)
@JsonQualifier
public @interface HexColor {
}

Next apply this @HexColor annotation to the appropriate field:

class Rectangle {
  int width;
  int height;
  @HexColor int color;
}

And finally define a type adapter to handle it:

/** Converts strings like #ff0000 to the corresponding color ints. */
class ColorAdapter {
  @ToJson String toJson(@HexColor int rgb) {
    return String.format("#%06x", rgb);
  }

  @FromJson @HexColor int fromJson(String rgb) {
    return Integer.parseInt(rgb.substring(1), 16);
  }
}

Use @JsonQualifier when you need different JSON encodings for the same type. Most programs
shouldn’t need this @JsonQualifier, but it’s very handy for those that do.

Omit fields with `transient`

Some models declare fields that shouldn’t be included in JSON. For example, suppose our blackjack
hand has a total field with the sum of the cards:

public final class BlackjackHand {
  private int total;

  ...
}

By default, all fields are emitted when encoding JSON, and all fields are accepted when decoding
JSON. Prevent a field from being included by adding Java’s transient keyword:

public final class BlackjackHand {
  private transient int total;

  ...
}

Transient fields are omitted when writing JSON. When reading JSON, the field is skipped even if the
JSON contains a value for the field. Instead it will get a default value.

Default Values & Constructors

When reading JSON that is missing a field, Moshi relies on the the Java or Android runtime to assign
the field’s value. Which value it uses depends on whether the class has a no-arguments constructor.

If the class has a no-arguments constructor, Moshi will call that constructor and whatever value
it assigns will be used. For example, because this class has a no-arguments constructor the total
field is initialized to -1.

public final class BlackjackHand {
  private int total = -1;
  ...

  private BlackjackHand() {
  }

  public BlackjackHand(Card hidden_card, List<Card> visible_cards) {
    ...
  }
}

If the class doesn’t have a no-arguments constructor, Moshi can’t assign the field’s default value,
even if it’s specified in the field declaration. Instead, the field’s default is always 0 for
numbers, false for booleans, and null for references. In this example, the default value of
total is 0!

public final class BlackjackHand {
  private int total = -1;
  ...

  public BlackjackHand(Card hidden_card, List<Card> visible_cards) {
    ...
  }
}

This is surprising and is a potential source of bugs! For this reason consider defining a
no-arguments constructor in classes that you use with Moshi, using @SuppressWarnings("unused") to
prevent it from being inadvertently deleted later:

public final class BlackjackHand {
  private int total = -1;
  ...

  @SuppressWarnings("unused") // Moshi uses this!
  private BlackjackHand() {
  }

  public BlackjackHand(Card hidden_card, List<Card> visible_cards) {
    ...
  }
}

Kotlin

Moshi is a great JSON library for Kotlin. It understands Kotlin’s non-nullable types and default
parameter values. When you use Kotlin with Moshi you may use reflection, codegen, or both.

Reflection

The reflection adapter uses Kotlin’s reflection library to convert your Kotlin classes to and from
JSON. Enable it by adding the KotlinJsonAdapterFactory to your Moshi.Builder:

val moshi = Moshi.Builder()
    // ... add your own JsonAdapters and factories ...
    .add(KotlinJsonAdapterFactory())
    .build()

Moshi’s adapters are ordered by precedence, so you always want to add the Kotlin adapter after your
own custom adapters. Otherwise the KotlinJsonAdapterFactory will take precedence and your custom
adapters will not be called.

The reflection adapter requires the following additional dependency:

<dependency>
  <groupId>com.squareup.moshi</groupId>
  <artifactId>moshi-kotlin</artifactId>
  <version>1.6.0</version>
</dependency>

implementation 'com.squareup.moshi:moshi-kotlin:1.6.0'

Note that the reflection adapter transitively depends on the kotlin-reflect library which is a
2.5 MiB .jar file.

Codegen

Moshi’s Kotlin codegen support is an annotation processor. It generates a small and fast adapter for
each of your Kotlin classes at compile time. Enable it by annotating each class that you want to
encode as JSON:

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

The codegen adapter requires that your Kotlin types and their properties be either internal or
public (this is Kotlin’s default visibility).

Kotlin codegen has no additional runtime dependency. You’ll need to [enable kapt][kapt] and then
add the following to your build to enable the annotation processor:

<dependency>
  <groupId>com.squareup.moshi</groupId>
  <artifactId>moshi-kotlin-codegen</artifactId>
  <version>1.6.0</version>
  <scope>provided</scope>
</dependency>

kapt 'com.squareup.moshi:moshi-kotlin-codegen:1.6.0'

You must also have the kotlin-stdlib dependency on the classpath during compilation in order for
the compiled code to have the required metadata annotations that Moshi's processor looks for.

Limitations

If your Kotlin class has a superclass, it must also be a Kotlin class. Neither reflection or codegen
support Kotlin types with Java supertypes or Java types with Kotlin supertypes. If you need to
convert such classes to JSON you must create a custom type adapter.

The JSON encoding of Kotlin types is the same whether using reflection or codegen. Prefer codegen
for better performance and to avoid the kotlin-reflect dependency; prefer reflection to convert
both private and protected properties. If you have configured both, generated adapters will be used
on types that are annotated @JsonClass(generateAdapter = true).

Download

Download [the latest JAR][dl] or depend via Maven:

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

or Gradle:

implementation 'com.squareup.moshi:moshi:1.6.0'

Snapshots of the development version are available in [Sonatype's snapshots repository][snap].

ProGuard

If you are using ProGuard you might need to add the following options:

-dontwarn okio.**
-dontwarn javax.annotation.**
-keepclasseswithmembers class * {
    @com.squareup.moshi.* <methods>;
}
-keep @com.squareup.moshi.JsonQualifier interface *

Additional rules are needed if you are using Kotlin:

...If you are using the reflect API (i.e. KotlinJsonAdapterFactory):

-keepclassmembers class kotlin.Metadata {
    public <methods>;
}

...If you are using the codegen API (i.e. JsonClass(generateAdapter = true)):

-keep class **JsonAdapter {
    <init>(...);
    <fields>;
}
-keepnames @com.squareup.moshi.JsonClass class *

A modern JSON library for Android and Java

Moshi

Built-in Type Adapters

Custom Type Adapters

Another example

Parse JSON Arrays

Fails Gracefully

Built on Okio

Borrows from Gson

Custom field names with @Json

Alternate type adapters with @JsonQualifier

Omit fields with `transient`

Default Values & Constructors

Kotlin

Reflection

Codegen

Limitations

Download

ProGuard

GitHub

JsonAnnotation can speed up Android development

A fast JSON parser/generator for Java

Moshi

Built-in Type Adapters

Custom Type Adapters

Another example

Parse JSON Arrays

Fails Gracefully

Built on Okio

Borrows from Gson

Custom field names with @Json

Alternate type adapters with @JsonQualifier

Omit fields with transient

Default Values & Constructors

Kotlin

Reflection

Codegen

Limitations

Download

ProGuard

GitHub

JsonAnnotation can speed up Android development

A fast JSON parser/generator for Java

You might also like...

Subscribe to Android Example 365

Omit fields with `transient`