Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/square/moshi

A modern JSON library for Kotlin and Java.
https://github.com/square/moshi

Last synced: 3 days ago
JSON representation

A modern JSON library for Kotlin and Java.

Awesome Lists containing this project

README 

        
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._



  Java



```java

String json = ...;



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

JsonAdapter jsonAdapter = moshi.adapter(BlackjackHand.class);



BlackjackHand blackjackHand = jsonAdapter.fromJson(json);

System.out.println(blackjackHand);

```



  Kotlin



```kotlin

val json: String = ...



val moshi: Moshi = Moshi.Builder().build()

val jsonAdapter: JsonAdapter = moshi.adapter()



val blackjackHand = jsonAdapter.fromJson(json)

println(blackjackHand)

```



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



    Java



```java

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 jsonAdapter = moshi.adapter(BlackjackHand.class);



String json = jsonAdapter.toJson(blackjackHand);

System.out.println(json);

```



    Kotlin



```kotlin

val blackjackHand = BlackjackHand(

    Card('6', SPADES),

    listOf(Card('4', CLUBS), Card('A', HEARTS))

  )



val moshi: Moshi = Moshi.Builder().build()

val jsonAdapter: JsonAdapter = moshi.adapter()



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:



    Java



```java

class BlackjackHand {

  public final Card hidden_card;

  public final List visible_cards;

  ...

}



class Card {

  public final char rank;

  public final Suit suit;

  ...

}



enum Suit {

  CLUBS, DIAMONDS, HEARTS, SPADES;

}

```



    Kotlin



```kotlin

class BlackjackHand(

  val hidden_card: Card,

  val visible_cards: List,

  ...

)



class Card(

  val rank: Char,

  val suit: Suit

  ...

)



enum class Suit {

  CLUBS, DIAMONDS, HEARTS, SPADES;

}

```



to read and write this JSON:



```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:



    Java



```java

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);

    }

  }

}

```



    Kotlin



```kotlin

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.



    Java



```java

Moshi moshi = new Moshi.Builder()

    .add(new CardAdapter())

    .build();

```



    Kotlin



```kotlin

val moshi = Moshi.Builder()

    .add(CardAdapter())

    .build()

```



Voilà:



```json

{

  "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.



```json

{

  "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:



    Java



```java

class Event {

  String title;

  String beginDateAndTime;

}

```



    Kotlin



```kotlin

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:



    Java



```java

class EventJson {

  String title;

  String begin_date;

  String begin_time;

}

```



    Kotlin



```kotlin

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.



    Java



```java

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;

  }

}

```



    Kotlin



```kotlin

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.



    Java



```java

Moshi moshi = new Moshi.Builder()

    .add(new EventJsonAdapter())

    .build();

```



    Kotlin



```kotlin

val moshi = Moshi.Builder()

    .add(EventJsonAdapter())

    .build()

```



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



    Java



```java

JsonAdapter jsonAdapter = moshi.adapter(Event.class);

Event event = jsonAdapter.fromJson(json);

```



    Kotlin



```kotlin

val jsonAdapter = moshi.adapter()

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:



    Java



```java

String dateJson = "\"2018-11-26T11:04:19.342668Z\"";

String nullDateJson = "null";



// Hypothetical IsoDateDapter, doesn't support null by default

JsonAdapter 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(nullDateJson);

System.out.println(nullDate); // null

```



    Kotlin



```kotlin

val dateJson = "\"2018-11-26T11:04:19.342668Z\""

val nullDateJson = "null"



// Hypothetical IsoDateDapter, doesn't support null by default

val adapter: JsonAdapter = IsoDateDapter()



val date = adapter.fromJson(dateJson)

println(date) // Mon Nov 26 12:04:19 CET 2018



val 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 to `nullSafe()` there is `nonNull()` to make an adapter refuse null values. Refer to the Moshi JavaDoc for details on the various methods.



### Parse JSON Arrays



Say we have a JSON string of this structure:



```json

[

  {

    "rank": "4",

    "suit": "CLUBS"

  },

  {

    "rank": "A",

    "suit": "HEARTS"

  }

]

```



We can now use Moshi to parse the JSON string into a `List`.



    Java



```java

String cardsJsonResponse = ...;

Type type = Types.newParameterizedType(List.class, Card.class);

JsonAdapter> adapter = moshi.adapter(type);

List cards = adapter.fromJson(cardsJsonResponse);

```



    Kotlin



```kotlin

val cardsJsonResponse: String = ...

// We can just use a reified extension!

val adapter = moshi.adapter>()

val cards: List = 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 or Kotlin classes have the same structure. But when they

don'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 name

contains spaces or other characters that aren’t permitted in Java field or Kotlin property names. For example, this

JSON has a field name containing a space:



```json

{

  "username": "jesse",

  "lucky number": 32

}

```



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



    Java



```java

class Player {

  String username;

  @Json(name = "lucky number") int luckyNumber;



  ...

}

```



    Kotlin



```kotlin

class Player {

  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 find

fields when navigating between Java or Koltin 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:



```json

{

  "width": 1024,

  "height": 768,

  "color": "#ff0000"

}

```



By convention, Android programs also use `int` for colors:



    Java



```java

class Rectangle {

  int width;

  int height;

  int color;

}

```



    Kotlin



```kotlin

class Rectangle(

  val width: Int,

  val height: Int,

  val color: Int

)

```



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



```json

{

  "width": 1024,

  "height": 768,

  "color": 16711680

}

```



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



    Java



```java

@Retention(RUNTIME)

@JsonQualifier

public @interface HexColor {

}

```



    Kotlin



```kotlin

@Retention(RUNTIME)

@JsonQualifier

annotation class HexColor

```



Next apply this `@HexColor` annotation to the appropriate field:



    Java



```java

class Rectangle {

  int width;

  int height;

  @HexColor int color;

}

```



    Kotlin



```kotlin

class Rectangle(

  val width: Int,

  val height: Int,

  @HexColor val color: Int

)

```



And finally define a type adapter to handle it:



    Java



```java

/** 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);

  }

}

```



    Kotlin



```kotlin

/** Converts strings like #ff0000 to the corresponding color ints.  */

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)

  }

}

```



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.



### Omitting fields



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:



    Java



```java

public final class BlackjackHand {

  private int total;



  ...

}

```



    Kotlin



```kotlin

class BlackjackHand(

  private val total: Int,



  ...

)

```



By default, all fields are emitted when encoding JSON, and all fields are accepted when decoding

JSON. Prevent a field from being included by annotating them with `@Json(ignore = true)`.



    Java



```java

public final class BlackjackHand {

  @Json(ignore = true)

  private int total;



  ...

}

```



    Kotlin



```kotlin

class BlackjackHand(...) {

  @Json(ignore = true)

  var total: Int = 0



  ...

}

```



These 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. In Kotlin, these fields

_must_ have a default value if they are in the primary constructor.



Note that you can also use Java’s `transient` keyword or Kotlin's `@Transient` annotation on these fields

for the same effect.



### Default Values & Constructors



When reading JSON that is missing a field, Moshi relies on the Java or Kotlin 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`.



Note: This section only applies to Java reflections.



```java

public final class BlackjackHand {

  private int total = -1;

  ...



  private BlackjackHand() {

  }



  public BlackjackHand(Card hidden_card, List 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`!



```java

public final class BlackjackHand {

  private int total = -1;

  ...



  public BlackjackHand(Card hidden_card, List 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:



```java

public final class BlackjackHand {

  private int total = -1;

  ...



  @SuppressWarnings("unused") // Moshi uses this!

  private BlackjackHand() {

  }



  public BlackjackHand(Card hidden_card, List visible_cards) {

    ...

  }

}

```



### Composing Adapters



In some situations Moshi's default Java-to-JSON conversion isn't sufficient. You can compose

adapters to build upon the standard conversion.



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



    Java



```java

class TournamentWithNullsAdapter {

  @ToJson void toJson(JsonWriter writer, Tournament tournament,

      JsonAdapter delegate) throws IOException {

    boolean wasSerializeNulls = writer.getSerializeNulls();

    writer.setSerializeNulls(true);

    try {

      delegate.toJson(writer, tournament);

    } finally {

      writer.setLenient(wasSerializeNulls);

    }

  }

}

```



    Kotlin



```kotlin

class TournamentWithNullsAdapter {

  @ToJson fun toJson(writer: JsonWriter, tournament: Tournament?,

    delegate: JsonAdapter) {

    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 JSON

document are skipped as usual.



Moshi has a powerful composition system in its `JsonAdapter.Factory` interface. We can hook in to

the encoding and decoding process for any type, even without knowing about the types beforehand. In

this example, we customize types annotated `@AlwaysSerializeNulls`, which an annotation we create,

not built-in to Moshi:



    Java



```java

@Target(TYPE)

@Retention(RUNTIME)

public @interface AlwaysSerializeNulls {}

```



    Kotlin



```kotlin

@Target(TYPE)

@Retention(RUNTIME)

annotation class AlwaysSerializeNulls

```



    Java



```java

@AlwaysSerializeNulls

static class Car {

  String make;

  String model;

  String color;

}

```



    Kotlin



```kotlin

@AlwaysSerializeNulls

class Car(

  val make: String?,

  val model: String?,

  val color: String?

)

```



Each `JsonAdapter.Factory` interface is invoked by `Moshi` when it needs to build an adapter for a

user's type. The factory either returns an adapter to use, or null if it doesn't apply to the

requested type. In our case we match all classes that have our annotation.



    Java



```java

static class AlwaysSerializeNullsFactory implements JsonAdapter.Factory {

  @Override public JsonAdapter> create(

      Type type, Set extends Annotation> annotations, Moshi moshi) {

    Class> rawType = Types.getRawType(type);

    if (!rawType.isAnnotationPresent(AlwaysSerializeNulls.class)) {

      return null;

    }



    JsonAdapter delegate = moshi.nextAdapter(this, type, annotations);

    return delegate.serializeNulls();

  }

}

```



    Kotlin



```kotlin

class AlwaysSerializeNullsFactory : JsonAdapter.Factory {

  override fun create(type: Type, annotations: Set, moshi: Moshi): JsonAdapter<*>? {

    val rawType: Class<*> = type.rawType

    if (!rawType.isAnnotationPresent(AlwaysSerializeNulls::class.java)) {

      return null

    }

    val delegate: JsonAdapter = moshi.nextAdapter(this, type, annotations)

    return delegate.serializeNulls()

  }

}

```



After determining that it applies, the factory looks up Moshi's built-in adapter by calling

`Moshi.nextAdapter()`. This is key to the composition mechanism: adapters delegate to each other!

The composition in this example is simple: it applies the `serializeNulls()` transform on the

delegate.



Composing adapters can be very sophisticated:



 * An adapter could transform the input object before it is JSON-encoded. A string could be

   trimmed 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 missing

   data 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-in

adapter for `List` delegates to the adapter of `T`, and calls it repeatedly.



### Precedence



Moshi's composition mechanism tries to find the best adapter for each type. It starts with the first

adapter or factory registered with `Moshi.Builder.add()`, and proceeds until it finds an adapter for

the target type.



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



To register an adapter at the end of the list, use `Moshi.Builder.addLast()` instead. This is most

useful when registering general-purpose adapters, such as the `KotlinJsonAdapterFactory` below.



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`:



```kotlin

val moshi = Moshi.Builder()

    .addLast(KotlinJsonAdapterFactory())

    .build()

```



Moshi’s adapters are ordered by precedence, so you should use `addLast()` with

`KotlinJsonAdapterFactory`, and `add()` with your custom adapters.



The reflection adapter requires the following additional dependency:



```xml



  com.squareup.moshi

  moshi-kotlin

  1.15.2



```



```kotlin

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

```



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 can be used as a Kotlin SymbolProcessor ([KSP][ksp]).

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:



```kotlin

@JsonClass(generateAdapter = true)

data class BlackjackHand(

  val hidden_card: Card,

  val visible_cards: List

)

```



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 or KSP and then

add the following to your build to enable the annotation processor:



    KSP



```kotlin

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")

}



```



#### 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:



```xml



  com.squareup.moshi

  moshi

  1.15.2



```

or Gradle:

```kotlin

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

```



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



R8 / ProGuard

--------



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.



#### Enums



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



License

--------



    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.0



    Unless required by applicable law or agreed to in writing, software

    distributed 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 and

    limitations under the License.



 [dl]: https://search.maven.org/classic/remote_content?g=com.squareup.moshi&a=moshi&v=LATEST

 [snap]: https://oss.sonatype.org/content/repositories/snapshots/com/squareup/moshi/

 [okio]: https://github.com/square/okio/

 [okhttp]: https://github.com/square/okhttp/

 [gson]: https://github.com/google/gson/

 [javadoc]: https://square.github.io/moshi/1.x/moshi/

 [ksp]: https://github.com/google/ksp