Repository files navigation

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

Note: The Kotlin examples of this README assume use of either Kotlin code gen orKotlinJsonAdapterFactory for reflection. Plain Java-based reflection is unsupported on Kotlin classes.

Stringjson = ...;Moshimoshi =newMoshi.Builder().build();JsonAdapter<BlackjackHand>jsonAdapter =moshi.adapter(BlackjackHand.class);BlackjackHandblackjackHand =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:

BlackjackHandblackjackHand =newBlackjackHand(newCard('6',SPADES),Arrays.asList(newCard('4',CLUBS),newCard('A',HEARTS)));Moshimoshi =newMoshi.Builder().build();JsonAdapter<BlackjackHand>jsonAdapter =moshi.adapter(BlackjackHand.class);Stringjson =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)

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 usesthese classes:

classBlackjackHand {publicfinalCardhidden_card;publicfinalList<Card>visible_cards;  ...}classCard {publicfinalcharrank;publicfinalSuitsuit;  ...}enumSuit {CLUBS,DIAMONDS,HEARTS,SPADES;}

classBlackjackHand(valhidden_card:Card,valvisible_cards:List<Card>,  ...)classCard(valrank:Char,valsuit:Suit  ...)enumclassSuit {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"    }  ]}

TheJavadoc catalogs the complete Moshi API, which we explore below.

With Moshi, it’s particularly easy to customize how values are converted to and from JSON. A typeadapter 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 andsuit in separate fields:{"rank":"A","suit":"HEARTS"}. With a type adapter, we can change theencoding to something more compact:"4H" for the four of hearts or"JD" for the jack ofdiamonds:

classCardAdapter {@ToJsonStringtoJson(Cardcard) {returncard.rank +card.suit.name().substring(0,1);  }@FromJsonCardfromJson(Stringcard) {if (card.length() !=2)thrownewJsonDataException("Unknown card: " +card);charrank =card.charAt(0);switch (card.charAt(1)) {case'C':returnnewCard(rank,Suit.CLUBS);case'D':returnnewCard(rank,Suit.DIAMONDS);case'H':returnnewCard(rank,Suit.HEARTS);case'S':returnnewCard(rank,Suit.SPADES);default:thrownewJsonDataException("unknown suit: " +card);    }  }}

classCardAdapter {  @ToJsonfuntoJson(card:Card):String {return card.rank+ card.suit.name.substring(0,1)  }  @FromJsonfunfromJson(card:String):Card {if (card.length!=2)throwJsonDataException("Unknown card:$card")val rank= card[0]returnwhen (card[1]) {'C'->Card(rank,Suit.CLUBS)'D'->Card(rank,Suit.DIAMONDS)'H'->Card(rank,Suit.HEARTS)'S'->Card(rank,Suit.SPADES)else->throwJsonDataException("unknown suit:$card")    }  }}

Register the type adapter with theMoshi.Builder and we’re good to go.

Moshimoshi =newMoshi.Builder()    .add(newCardAdapter())    .build();

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

Voilà:

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

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 typeand then use the@FromJson method to produce the desired final value. Conversely, the methodannotated 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 arerepresented 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 alater point. Also, we would like to have all variable names in CamelCase. Therefore, theEventclass we want Moshi to produce like this:

classEvent {Stringtitle;StringbeginDateAndTime;}

classEvent(valtitle:String,valbeginDateAndTime:String)

Instead of manually parsing the JSON line per line (which we could also do) we can have Moshi do thetransformation automatically. We simply define another classEventJson that directly correspondsto the JSON structure:

classEventJson {Stringtitle;Stringbegin_date;Stringbegin_time;}

classEventJson(valtitle:String,valbegin_date:String,valbegin_time:String)

And another class with the appropriate@FromJson and@ToJson methods that are telling Moshi howto convert anEventJson to anEvent and back. Now, whenever we are asking Moshi to parse a JSONto anEvent it will first parse it to anEventJson as an intermediate step. Conversely, toserialize anEvent Moshi will first create anEventJson object and then serialize that object asusual.

classEventJsonAdapter {@FromJsonEventeventFromJson(EventJsoneventJson) {Eventevent =newEvent();event.title =eventJson.title;event.beginDateAndTime =eventJson.begin_date +" " +eventJson.begin_time;returnevent;  }@ToJsonEventJsoneventToJson(Eventevent) {EventJsonjson =newEventJson();json.title =event.title;json.begin_date =event.beginDateAndTime.substring(0,8);json.begin_time =event.beginDateAndTime.substring(9,14);returnjson;  }}

classEventJsonAdapter {  @FromJsonfuneventFromJson(eventJson:EventJson):Event {returnEvent(      title= eventJson.title,      beginDateAndTime="${eventJson.begin_date}${eventJson.begin_time}"    )  }  @ToJsonfuneventToJson(event:Event):EventJson {returnEventJson(      title= event.title,      begin_date= event.beginDateAndTime.substring(0,8),      begin_time= event.beginDateAndTime.substring(9,14),    )  }}

Again we register the adapter with Moshi.

Moshimoshi =newMoshi.Builder()    .add(newEventJsonAdapter())    .build();

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

We can now use Moshi to parse the JSON directly to anEvent.

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

val jsonAdapter= moshi.adapter<Event>()val event= jsonAdapter.fromJson(json)

Moshi provides a number of convenience methods forJsonAdapter objects:

• nullSafe()
• nonNull()
• lenient()
• failOnUnknown()
• indent()
• serializeNulls()

These factory methods wrap an existingJsonAdapter into additional functionality.For example, if you have an adapter that doesn't support nullable values, you can usenullSafe() to make it null safe:

StringdateJson ="\"2018-11-26T11:04:19.342668Z\"";StringnullDateJson ="null";// Hypothetical IsoDateDapter, doesn't support null by defaultJsonAdapter<Date>adapter =newIsoDateDapter();Datedate =adapter.fromJson(dateJson);System.out.println(date);// Mon Nov 26 12:04:19 CET 2018DatenullDate =adapter.fromJson(nullDateJson);// Exception, com.squareup.moshi.JsonDataException: Expected a string but was NULL at path $DatenullDate =adapter.nullSafe().fromJson(nullDateJson);System.out.println(nullDate);// null

val dateJson="\"2018-11-26T11:04:19.342668Z\""val nullDateJson="null"// Hypothetical IsoDateDapter, doesn't support null by defaultval adapter:JsonAdapter<Date>=IsoDateDapter()val date= adapter.fromJson(dateJson)println(date)// Mon Nov 26 12:04:19 CET 2018val nullDate= adapter.fromJson(nullDateJson)// Exception, com.squareup.moshi.JsonDataException: Expected a string but was NULL at path $val nullDate= adapter.nullSafe().fromJson(nullDateJson)println(nullDate)// null

In contrast tonullSafe() there isnonNull() to make an adapter refuse null values. Refer to the Moshi JavaDoc for details on the various methods.

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 aList<Card>.

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

val cardsJsonResponse:String=...// We can just use a reified extension!val adapter= moshi.adapter<List<Card>>()val cards:List<Card>= adapter.fromJson(cardsJsonResponse)

Automatic databinding almost feels like magic. But unlike the black magic that typically accompaniesreflection, 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 standardjava.io.IOException if there is an error reading the JSON document,or if it is malformed. It throws aJsonDataException if the JSON document is well-formed, butdoesn’t match the expected format.

Moshi usesOkio for simple and powerful I/O. It’s a fine complement toOkHttp,which can share buffer segments for maximum efficiency.

Moshi uses the same streaming and binding mechanisms asGson. If you’re a Gson user you’llfind Moshi works similarly. If you try Moshi and don’t love it, you can even migrate to Gson withoutmuch 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 dateadapter. Most binding libraries will encode whatever you throw at them. Moshi refuses toserialize platform types (java.*,javax.*, andandroid.*) without a user-provided typeadapter. This is intended to prevent you from accidentally locking yourself to a specific JDK orAndroid release.
• Moshi is less configurable. There’s no field naming strategy, versioning, instance creators,or long serialization policy. Instead of naming a fieldvisibleCards and using a policy classto convert that tovisible_cards, Moshi wants you to just name the fieldvisible_cards as itappears in the JSON.
• Moshi doesn’t have aJsonElement model. Instead it just uses built-in types likeList andMap.
• No HTML-safe escaping. Gson encodes= as\u003d by default so that it can be safelyencoded in HTML without additional escaping. Moshi encodes it naturally (as=) and assumes thatthe HTML encoder – if there is one – will do its job.

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

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

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

With@Json its corresponding Java or Kotlin class is easy:

classPlayer {Stringusername;@Json(name ="lucky number")intluckyNumber;  ...}

classPlayer {val username:String  @Json(name="lucky number")val luckyNumber:Int...}

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

Use@JsonQualifier to customize how a type is encoded for some fields without changing itsencoding everywhere. This works similarly to the qualifier annotations in dependency injectiontools 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 useint for colors:

classRectangle {intwidth;intheight;intcolor;}

classRectangle(valwidth:Int,valheight:Int,valcolor:Int)

But if we encoded the above Java or Kotlin 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)@JsonQualifierpublic @interfaceHexColor {}

@Retention(RUNTIME)@JsonQualifierannotationclassHexColor

Next apply this@HexColor annotation to the appropriate field:

classRectangle {intwidth;intheight;@HexColorintcolor;}

classRectangle(valwidth:Int,valheight:Int,  @HexColorvalcolor:Int)

And finally define a type adapter to handle it:

/** Converts strings like #ff0000 to the corresponding color ints. */classColorAdapter {@ToJsonStringtoJson(@HexColorintrgb) {returnString.format("#%06x",rgb);  }@FromJson@HexColorintfromJson(Stringrgb) {returnInteger.parseInt(rgb.substring(1),16);  }}

/** Converts strings like #ff0000 to the corresponding color ints.*/classColorAdapter {  @ToJsonfuntoJson(@HexColorrgb:Int):String {return"#%06x".format(rgb)  }  @FromJson @HexColorfunfromJson(rgb:String):Int {return rgb.substring(1).toInt(16)  }}

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

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

publicfinalclassBlackjackHand {privateinttotal;  ...}

classBlackjackHand(privatevaltotal:Int,  ...)

By default, all fields are emitted when encoding JSON, and all fields are accepted when decodingJSON. Prevent a field from being included by annotating them with@Json(ignore = true).

publicfinalclassBlackjackHand {@Json(ignore =true)privateinttotal;  ...}

classBlackjackHand(...) {  @Json(ignore=true)var total:Int=0...}

These fields are omitted when writing JSON. When reading JSON, the field is skipped even if theJSON contains a value for the field. Instead, it will get a default value. In Kotlin, these fieldsmust have a default value if they are in the primary constructor.

Note that you can also use Java’stransient keyword or Kotlin's@Transient annotation on these fieldsfor the same effect.

When reading JSON that is missing a field, Moshi relies on the Java or Kotlin or Android runtime to assignthe 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 valueit assigns will be used. For example, because this class has a no-arguments constructor thetotalfield is initialized to-1.

Note: This section only applies to Java reflections.

publicfinalclassBlackjackHand {privateinttotal = -1;  ...privateBlackjackHand() {  }publicBlackjackHand(Cardhidden_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 always0 fornumbers,false for booleans, andnull for references. In this example, the default value oftotal is0!

publicfinalclassBlackjackHand {privateinttotal = -1;  ...publicBlackjackHand(Cardhidden_card,List<Card>visible_cards) {    ...  }}

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

publicfinalclassBlackjackHand {privateinttotal = -1;  ...@SuppressWarnings("unused")// Moshi uses this!privateBlackjackHand() {  }publicBlackjackHand(Cardhidden_card,List<Card>visible_cards) {    ...  }}

In some situations Moshi's default Java-to-JSON conversion isn't sufficient. You can composeadapters to build upon the standard conversion.

In this example, we turn serialize nulls, then delegate to the built-in adapter:

classTournamentWithNullsAdapter {@ToJsonvoidtoJson(JsonWriterwriter,Tournamenttournament,JsonAdapter<Tournament>delegate)throwsIOException {booleanwasSerializeNulls =writer.getSerializeNulls();writer.setSerializeNulls(true);try {delegate.toJson(writer,tournament);    }finally {writer.setLenient(wasSerializeNulls);    }  }}

classTournamentWithNullsAdapter {  @ToJsonfuntoJson(writer:JsonWriter,tournament:Tournament?,delegate:JsonAdapter<Tournament?>) {val wasSerializeNulls:Boolean= writer.getSerializeNulls()    writer.setSerializeNulls(true)try {      delegate.toJson(writer, tournament)    }finally {      writer.setLenient(wasSerializeNulls)    }  }}

When we use this to serialize a tournament, nulls are written! But nulls elsewhere in our JSONdocument are skipped as usual.

Moshi has a powerful composition system in itsJsonAdapter.Factory interface. We can hook in tothe encoding and decoding process for any type, even without knowing about the types beforehand. Inthis example, we customize types annotated@AlwaysSerializeNulls, which an annotation we create,not built-in to Moshi:

@Target(TYPE)@Retention(RUNTIME)public @interfaceAlwaysSerializeNulls {}

@Target(TYPE)@Retention(RUNTIME)annotationclassAlwaysSerializeNulls

@AlwaysSerializeNullsstaticclassCar {Stringmake;Stringmodel;Stringcolor;}

@AlwaysSerializeNullsclassCar(valmake:String?,valmodel:String?,valcolor:String?)

EachJsonAdapter.Factory interface is invoked byMoshi when it needs to build an adapter for auser's type. The factory either returns an adapter to use, or null if it doesn't apply to therequested type. In our case we match all classes that have our annotation.

staticclassAlwaysSerializeNullsFactoryimplementsJsonAdapter.Factory {@OverridepublicJsonAdapter<?>create(Typetype,Set<?extendsAnnotation>annotations,Moshimoshi) {Class<?>rawType =Types.getRawType(type);if (!rawType.isAnnotationPresent(AlwaysSerializeNulls.class)) {returnnull;    }JsonAdapter<Object>delegate =moshi.nextAdapter(this,type,annotations);returndelegate.serializeNulls();  }}

classAlwaysSerializeNullsFactory :JsonAdapter.Factory {overridefuncreate(type:Type,annotations:Set<Annotation>,moshi:Moshi):JsonAdapter<*>? {val rawType:Class<*>= type.rawTypeif (!rawType.isAnnotationPresent(AlwaysSerializeNulls::class.java)) {returnnull    }val delegate:JsonAdapter<Any>= moshi.nextAdapter(this, type, annotations)return delegate.serializeNulls()  }}

After determining that it applies, the factory looks up Moshi's built-in adapter by callingMoshi.nextAdapter(). This is key to the composition mechanism: adapters delegate to each other!The composition in this example is simple: it applies theserializeNulls() transform on thedelegate.

Composing adapters can be very sophisticated:

• An adapter could transform the input object before it is JSON-encoded. A string could betrimmed or truncated; a value object could be simplified or normalized.

• An adapter could repair the output object after it is JSON-decoded. It could fill-in missingdata or discard unwanted data.

• The JSON could be given extra structure, such as wrapping values in objects or arrays.

Moshi is itself built on the pattern of repeatedly composing adapters. For example, Moshi's built-inadapter forList<T> delegates to the adapter ofT, and calls it repeatedly.

Moshi's composition mechanism tries to find the best adapter for each type. It starts with the firstadapter or factory registered withMoshi.Builder.add(), and proceeds until it finds an adapter forthe target type.

If a type can be matched multiple adapters, the earliest one wins.

To register an adapter at the end of the list, useMoshi.Builder.addLast() instead. This is mostuseful when registering general-purpose adapters, such as theKotlinJsonAdapterFactory below.

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

The reflection adapter uses Kotlin’s reflection library to convert your Kotlin classes to and fromJSON. Enable it by adding theKotlinJsonAdapterFactory to yourMoshi.Builder:

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

Moshi’s adapters are ordered by precedence, so you should useaddLast() withKotlinJsonAdapterFactory, andadd() with your custom adapters.

The reflection adapter requires the following additional dependency:

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

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

Note that the reflection adapter transitively depends on thekotlin-reflect library which is a2.5 MiB .jar file.

Moshi’s Kotlin codegen support can be used as a Kotlin SymbolProcessor (KSP).It generates a small and fast adapter for each of your Kotlin classes at compile-time. Enable it by annotatingeach class that you want to encode as JSON:

@JsonClass(generateAdapter=true)data classBlackjackHand(valhidden_card:Card,valvisible_cards:List<Card>)

The codegen adapter requires that your Kotlin types and their properties be eitherinternal orpublic (this is Kotlin’s default visibility).

Kotlin codegen has no additional runtime dependency. You’ll need to enable kapt or KSP and thenadd the following to your build to enable the annotation processor:

plugins {  id("com.google.devtools.ksp").version("1.6.10-1.0.4")// Or latest version of KSP}dependencies {  ksp("com.squareup.moshi:moshi-kotlin-codegen:1.15.2")}

If your Kotlin class has a superclass, it must also be a Kotlin class. Neither reflection or codegensupport Kotlin types with Java supertypes or Java types with Kotlin supertypes. If you need toconvert 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 codegenfor better performance and to avoid thekotlin-reflect dependency; prefer reflection to convertboth private and protected properties. If you have configured both, generated adapters will be usedon types that are annotated@JsonClass(generateAdapter = true).

Downloadthe latest JAR or depend via Maven:

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

or Gradle:

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

Snapshots of the development version are available inSonatype'ssnapshots repository.

Moshi contains minimally required rules for its own internals to work without need for consumers to embed their own. However if you are using reflective serialization and R8 or ProGuard, you must add keep rules in your proguard configuration file for your reflectively serialized classes.

Annotate enums with@JsonClass(generateAdapter = false) to prevent them from being removed/obfuscated from your code by R8/ProGuard.

Copyright 2015 Square, Inc.Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at   http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.