Moshi
A modern JSON library for Kotlin and Java.
Install / Use
/learn @square/MoshiREADME
Moshi
Moshi is a modern JSON library for Android, Java and Kotlin. It makes it easy to parse JSON into Java and Kotlin classes:
Note: The Kotlin examples of this README assume use of either Kotlin code gen or KotlinJsonAdapterFactory for reflection. Plain Java-based reflection is unsupported on Kotlin classes.
String json = ...;
Moshi moshi = new Moshi.Builder().build();
JsonAdapter<BlackjackHand> jsonAdapter = moshi.adapter(BlackjackHand.class);
BlackjackHand blackjackHand = jsonAdapter.fromJson(json);
System.out.println(blackjackHand);
val json: String = ...
val moshi: Moshi = Moshi.Builder().build()
val jsonAdapter: JsonAdapter<BlackjackHand> = moshi.adapter<BlackjackHand>()
val blackjackHand = jsonAdapter.fromJson(json)
println(blackjackHand)
And it can just as easily serialize Java or Kotlin objects as JSON:
<details> <summary>Java</summary>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);
val blackjackHand = BlackjackHand(
Card('6', SPADES),
listOf(Card('4', CLUBS), Card('A', HEARTS))
)
val moshi: Moshi = Moshi.Builder().build()
val jsonAdapter: JsonAdapter<BlackjackHand> = moshi.adapter<BlackjackHand>()
val json: String = jsonAdapter.toJson(blackjackHand)
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:
<details> <summary>Java</summary>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;
}
class BlackjackHand(
val hidden_card: Card,
val visible_cards: List<Card>,
...
)
class Card(
val rank: Char,
val suit: Suit
...
)
enum class 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);
}
}
}
class CardAdapter {
@ToJson fun toJson(card: Card): String {
return card.rank + card.suit.name.substring(0, 1)
}
@FromJson fun fromJson(card: String): Card {
if (card.length != 2) throw JsonDataException("Unknown card: $card")
val rank = card[0]
return when (card[1]) {
'C' -> Card(rank, Suit.CLUBS)
'D' -> Card(rank, Suit.DIAMONDS)
'H' -> Card(rank, Suit.HEARTS)
'S' -> Card(rank, Suit.SPADES)
else -> throw JsonDataException("unknown suit: $card")
}
}
}
Register the type adapter with the Moshi.Builder and we’re good to go.
Moshi moshi = new Moshi.Builder()
.add(new CardAdapter())
.build();
val moshi = Moshi.Builder()
.add(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;
}
class Event(
val title: String,
val beginDateAndTime: String
)
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;
}
class EventJson(
val title: String,
val begin_date: String,
val begin_time: String
)
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;
}
}
class EventJsonAdapter {
@FromJson
fun eventFromJson(eventJson: EventJson): Event {
return Event(
title = eventJson.title,
beginDateAndTime = "${eventJson.begin_date} ${eventJson.begin_time}"
)
}
@ToJson
fun eventToJson(event: Event): EventJson {
return EventJson(
title = event.title,
begin_date = event.beginDateAndTime.substring(0, 8),
begin_time = event.beginDateAndTime.substring(9, 14),
)
}
}
Again we register the adapter with Moshi.
<details> <summary>Java</summary>Moshi moshi = new Moshi.Builder()
.add(new EventJsonAdapter())
.build();
val moshi = Moshi.Builder()
.add(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);
val jsonAdapter = moshi.adapter<Event>()
val event = jsonAdapter.fromJson(json)
Adapter convenience methods
Moshi provides a number of convenience methods for JsonAdapter objects:
nullSafe()nonNull()lenient()failOnUnknown()indent()serializeNulls()
These factory methods wrap an existing JsonAdapter into additional functionality.
For example, if you have an adapter that doesn't support nullable values, you can use nullSafe() to make it null safe:
String dateJson = "\"2018-11-26T11:04:19.342668Z\"";
String nullDateJson = "null";
// Hypothetical IsoDateDapter, doesn't support null by default
JsonAdapter<Date> adapter = new IsoDateDapter();
Date date = adapter.fromJson(dateJson);
System.out.println(date); // Mon Nov 26 12:04:19 CET 2018
Date nullDate = adapter.fromJson(nullDateJson);
// Exception, com.squareup.moshi.JsonDataException: Expected a string but was NULL at path $
Date nullDate = adapter.nullSafe().fromJson(nullDateJs
