Custom scalar types in Apollo Kotlin

In addition to its built-in scalar types (Int, String, etc.), GraphQL supports defining custom scalars. For example, your schema might define a custom scalar for Long, Date, BigDecimal, or GeoPoint.

Define class mapping

To interact with custom scalars in your Apollo Kotlin app, you need to define a mapping in your build.gradle[.kts] file. This tells Apollo Kotlin which class to use to represent each custom scalar from your schema.

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    mapScalar("GeoPoint", "com.example.GeoPoint")
4

5
    // Shortcuts exist for standard types - equivalent to mapScalar("Long", "kotlin.Long")
6
    mapScalarToKotlinLong("Long")
7
  }
8
}

If needed, you can also do this with a built-in scalar (such as ID) to override its default type.

Define class adapters

Each class you use to represent a custom scalar also requires an adapter to convert it to and from the JSON format that's sent over the network.

Each adapter requires a fromJson function. A toJson function is also required if your app ever passes the custom scalar as a GraphQL argument.

Here's an adapter for a GeoPoint custom scalar:

1
class GeoPoint(val latitude: Double, val longitude: Double)
2

3
val geoPointAdapter = object : Adapter<GeoPoint> {
4
  override fun fromJson(reader: JsonReader, customScalarAdapters: CustomScalarAdapters): GeoPoint {
5
    var latitude: Double? = null
6
    var longitude: Double? = null
7
    reader.beginObject()
8
    while(reader.hasNext()) {
9
      when (reader.nextName()) {
10
        "latitude" -> latitude = reader.nextDouble()
11
        "longitude" -> longitude = reader.nextDouble()
12
      }
13
    }
14
    reader.endObject()
15

16
    // fromJson can throw on unexpected data and the exception will be wrapped in a
17
    // ApolloParseException
18
    return GeoPoint(latitude!!, longitude!!)
19
  }
20

21
  // If you do not expect your scalar to be used as input, you can leave this method as TODO()
22
  override fun toJson(writer: JsonWriter, customScalarAdapters: CustomScalarAdapters, value: GeoPoint) {
23
    writer.beginObject()
24
    writer.name("latitude").value(value.latitude)
25
    writer.name("longitude").value(value.longitude)
26
    writer.endObject()
27
  }
28
}

If you prefer working with Maps, Apollo Kotlin comes with AnyAdapter, which supports adapting String, Int, Double, Boolean, List, and Map. You can use it in an intermediate step:

1
val geoPointAdapter = object : Adapter<GeoPoint> {
2
  override fun fromJson(reader: JsonReader, customScalarAdapters: CustomScalarAdapters): GeoPoint {
3
    val map = AnyAdapter.fromJson(reader) as Map<String, Double>
4
    return GeoPoint(map["latitude"] as Double, map["longitude"] as Double)
5
  }
6

7
  override fun toJson(writer: JsonWriter, customScalarAdapters: CustomScalarAdapters, value: GeoPoint) {
8
    val map = mapOf(
9
        "latitude" to value.latitude,
10
        "longitude" to value.longitude
11
    )
12
    AnyAdapter.toJson(writer, map)
13
  }
14
}

This solution is more concise but slightly less performant.

Register adapters

After you define your adapters, you need to register them. This can be done either in the build.gradle[.kts] file, or at runtime.

In `build.gradle[.kts]`

A third argument can be passed to mapScalar to specify the adapter to use:

build.gradle[.kts]

1
apollo {
2
  service("service") {
3
    mapScalar("GeoPoint", "com.example.GeoPoint", "com.example.Adapters.geoPointAdapter")
4
  }
5
}

The given expression is copied as-is in the generated code. Therefore, it's possible to pass any of the following:

An instantiation expression, like "com.example.GeoPointAdapter()"
A singleton reference, like "com.example.GeoPointAdapter"
A function call, like "com.example.Adapters.getGeoPointAdapter()"

Make sure you pass the full class name including the package, because imports aren't automatically generated.

At runtime

You can also register adapters on your ApolloClient instance by calling ApolloClient.Builder.addCustomScalarAdapter once for each adapter:

1
val apolloClient = ApolloClient.Builder().serverUrl("https://example.com/graphql")
2
    .addCustomScalarAdapter(GeoPoint.type, geoPointAdapter)
3
    .build()

This method takes a type-safe generated class from Types, along with its corresponding adapter.

If you can't find Types, build your project to trigger codegen.

Apollo-provided adapters

The following built-in adapters can be used with common custom scalar types:

Adapter	Description
`com.apollographql.apollo3.api.FloatAdapter`	Converts from/to `kotlin.Float`/`java.lang.Float`
`com.apollographql.apollo3.api.LongAdapter`	Converts from/to `kotlin.Long`/`java.lang.Long`

In addition, the com.apollographql.apollo3:apollo-adapters artifact provides these adapters:

Adapter	Description
`com.apollographql.apollo3.adapter.KotlinxInstantAdapter`	For `kotlinx.datetime.Instant` ISO8601 dates
`com.apollographql.apollo3.adapter.JavaInstantAdapter`	For `java.time.Instant` ISO8601 dates
`com.apollographql.apollo3.adapter.KotlinxLocalDateAdapter`	For `kotlinx.datetime.LocalDate` ISO8601 dates
`com.apollographql.apollo3.adapter.JavaLocalDateAdapter`	For `java.time.LocalDate` ISO8601 dates
`com.apollographql.apollo3.adapter.KotlinxLocalDateTimeAdapter`	For `kotlinx.datetime.LocalDateTime` ISO8601 dates
`com.apollographql.apollo3.adapter.JavaLocalDateTimeAdapter`	For `java.time.LocalDateTime` ISO8601 dates
`com.apollographql.apollo3.adapter.KotlinxLocalTimeAdapter`	For `kotlinx.datetime.LocalTime` ISO8601 dates
`com.apollographql.apollo3.adapter.JavaLocalTimeAdapter`	For `java.time.LocalTime` ISO8601 dates
`com.apollographql.apollo3.adapter.JavaOffsetDateTimeAdapter`	For `java.time.OffsetDateTime` ISO8601 dates
`com.apollographql.apollo3.adapter.DateAdapter`	For `java.util.Date` ISO8601 dates
`com.apollographql.apollo3.adapter.BigDecimalAdapter`	For a Multiplatform `com.apollographql.apollo3.adapter.BigDecimal` class holding big decimal values

ⓘ NOTE

Because some adapters use kotlinx.datetime (which itself uses java.time), you need to enable core library desugaring on Android API levels < 26

For example, to use DateAdapter, configure your Gradle scripts like so:

build.gradle[.kts]

1
dependencies {
2
  implementation("com.apollographql.apollo3:apollo-adapters:4.0.0-beta.7")
3
}
4

5
apollo {
6
  service("service") {
7
    mapScalar("Date", "java.util.Date", "com.apollographql.apollo3.adapter.DateAdapter")
8
  }
9
}

Error handling

Fragments

Custom scalar types in Apollo Kotlin

Define class mapping

Define class adapters

Register adapters

In build.gradle[.kts]

At runtime

Apollo-provided adapters

In `build.gradle[.kts]`