kotlinx.serialization使い方｜JSON変換・設定一覧・エラー

kotlinx.serialization は、Kotlin 公式の JSON 変換ライブラリです。 クラスに @Serializable を付け、Json.encodeToString(値) で JSON 文字列に、Json.decodeFromString<型>(文字列) でオブジェクトに戻します。リフレクション（実行時に型を調べるしくみ）を使わず、コンパイラプラグインが変換コードを作ります。

@Serializable
data class User(val id: Long, val name: String, val email: String? = null)

val json = Json.encodeToString(User(1, "Ito"))        // {"id":1,"name":"Ito"}
val user = Json.decodeFromString<User>(json)          // User(id=1, name=Ito, email=null)

確認環境：kotlinx.serialization 1.11.0（GitHub の CHANGELOG で最新の安定版。2026年4月10日公開）と kotlinx-datetime 0.8.0 を、GitHub のソース（タグ v1.11.0・v0.8.0）から Kotlin コンパイラ kotlinc 2.4.20 で JVM 向けにビルドし、同梱のシリアライズ用コンパイラプラグインと組み合わせて、OpenJDK 21.0.10・Linux で実行しました。本文の出力とエラー文は、この実行で得たものです。依存の書き方は kotlinlang.org のドキュメントで確かめました（確認日 2026年10月12日）。

依存の書き方

「コンパイラプラグイン」と「ライブラリ」の2つが必要です。 片方だけでは動きません。

// build.gradle.kts
plugins {
    kotlin("jvm") version "2.4.21"
    kotlin("plugin.serialization") version "2.4.21"   // Kotlin と同じ版
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.11.0")
}

Maven では kotlin-maven-plugin の <compilerPlugins> に kotlinx-serialization を書き、プラグインの依存に org.jetbrains.kotlin:kotlin-maven-serialization を足します（kotlinlang.org の例）。Version Catalog で書く方法は、関連記事「build.gradle.kts書き方｜Groovy対応表とバージョンカタログ」で扱っています。

プラグインを入れ忘れると

プラグインなしでコンパイルすると、コンパイルは通り、実行したときに次の例外になりました。

kotlinx.serialization.SerializationException: Serializer for class 'P' is not found.
Please ensure that class is marked as '@Serializable' and that the serialization compiler plugin is applied.

@Serializable を付けたのにこのエラーが出るときは、まずプラグインを確かめます。

基本：encodeToString と decodeFromString

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.encodeToString
import kotlinx.serialization.decodeFromString

@Serializable
data class User(
    val id: Long,
    val name: String,
    val email: String? = null,
    val tags: List<String> = emptyList(),
)

fun main() {
    println(Json.encodeToString(User(1, "Ito")))
    println(Json.decodeFromString<User>("""{"id":2,"name":"Sato","email":"s@example.com","tags":["a"]}"""))
    println(Json.encodeToString(listOf(User(1, "A"), User(2, "B"))))
    println(Json.decodeFromString<Map<String, Int>>("""{"a":1,"b":2}"""))
}

{"id":1,"name":"Ito"}
User(id=2, name=Sato, email=s@example.com, tags=[a])
[{"id":1,"name":"A"},{"id":2,"name":"B"}]
{a=1, b=2}

既定値と同じ値のプロパティ（email = null・tags = []）は、出力されません。 これが kotlinx.serialization の既定の動きです（encodeDefaults = false）。List・Map・Set などのコレクションは、そのまま変換できます。

Json のインスタンスは使い回す

Json { … } を関数の中で毎回作るコードをコンパイルすると、プラグインが次の警告を出しました。

warning: redundant creation of Json format. Creating instances for each use can be slow.

設定済みの Json は、トップレベルの val などに1つ作って使い回します。

val AppJson = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
}

注釈：@SerialName・@Transient・@Required・@EncodeDefault

@Serializable
data class Article(
    @SerialName("article_id") val id: Long,
    val title: String,
    @Transient val cache: String = "not serialized",
    val status: Status = Status.DRAFT,
    @EncodeDefault val version: Int = 1,
    @Required val lang: String = "ja",
)

@Serializable
enum class Status {
    @SerialName("draft") DRAFT,
    @SerialName("published") PUBLISHED,
}

Json.encodeToString(Article(10, "Hello"))
{"article_id":10,"title":"Hello","version":1,"lang":"ja"}

Json { encodeDefaults = true }.encodeToString(Article(10, "Hello"))
{"article_id":10,"title":"Hello","status":"draft","version":1,"lang":"ja"}

@Transient は kotlinx.serialization.Transient です。JVM の kotlin.jvm.Transient（Java の transient 修飾子）とは別のものなので、import を確かめます。

既定値の無いプロパティは、JSON に必須です。 既定値があるプロパティは、JSON に無ければ既定値になります。この「既定値があるかどうか」が、MissingFieldException が出るかどうかの分かれ目です。

Json の設定項目の早見表（既定値はソースで確認）

既定値は v1.11.0 の JsonConfiguration のソースの値です。

設定ごとの実行結果

explicitNulls = false は、読むときにも効きます。 既定値の無い val note: String? が JSON に無いとき、既定の設定では MissingFieldException でしたが、explicitNulls = false では note=null で読めました。

coerceInputValues は、null と知らない enum 値のどちらも既定値に置き換えます。 既定値の無いプロパティでは置き換えられません。

prettyPrint = true の出力です。

{
    "id": 1,
    "name": "Ito"
}

REST API のクライアントでよく使う組み合わせ

val ApiJson = Json {
    ignoreUnknownKeys = true      // API 側が項目を足しても壊れない
    explicitNulls = false         // null を送らない・無い項目を null で読む
    coerceInputValues = true      // 想定外の enum 値を既定値で受ける
}

ignoreUnknownKeys は便利ですが、キー名の綴り違いにも気づかなくなります。自分たちで JSON を作る設定ファイルなどでは、既定の厳しい設定のほうが誤りを見つけやすくなります。

日付と時刻

java.time.LocalDate には、そのままでは対応していません。 @Serializable のクラスに LocalDate 型のプロパティを書くと、コンパイルの時点で止まりました。

error: serializer was not found for type 'LocalDate'. To use a context serializer as the fallback, explicitly annotate type or property with '@Contextual'.

方法は3つあります。

kotlinx-datetime を使う

kotlinx-datetime の型は、最初から @Serializable に対応しています。ISO 8601 の形式で出力されます。

// 依存：implementation("org.jetbrains.kotlinx:kotlinx-datetime:0.8.0")
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlinx.datetime.serializers.FormattedLocalDateSerializer
import kotlin.time.Instant

// 2026/10/12 の形式で読み書きする
object SlashDateSerializer : FormattedLocalDateSerializer(
    "com.example.SlashDate",
    LocalDate.Format { year(); char('/'); monthNumber(); char('/'); day() }
)

@Serializable
data class Reservation(
    val date: LocalDate,
    val start: LocalDateTime,
    val at: Instant,
    @Serializable(with = SlashDateSerializer::class) val shown: LocalDate,
)

{"date":"2026-10-12","start":"2026-10-12T09:30","at":"2026-10-12T00:30:00Z","shown":"2026/10/12"}
Reservation(date=2026-10-12, start=2026-10-12T09:30, at=2026-10-12T00:30:00Z, shown=2026-10-12)

存在しない日付（"2026-13-01"）を読むと、kotlinx.datetime.DateTimeFormatException（中身は Invalid value for MonthOfYear (valid values 1 - 12): 13）になりました。

kotlinx-datetime の README では、0.7.0 から Instant と Clock は標準ライブラリの kotlin.time のものを使う形に変わっています。kotlinx.serialization 1.11.0 には、kotlin.time.Instant 用のシリアライザが入っています。

java.time.LocalDate 用の KSerializer を書く

import kotlinx.serialization.KSerializer
import kotlinx.serialization.descriptors.PrimitiveKind
import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
import kotlinx.serialization.descriptors.SerialDescriptor
import kotlinx.serialization.encoding.Decoder
import kotlinx.serialization.encoding.Encoder
import java.time.LocalDate

object LocalDateSerializer : KSerializer<LocalDate> {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("java.time.LocalDate", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: LocalDate) =
        encoder.encodeString(value.toString())

    override fun deserialize(decoder: Decoder): LocalDate =
        LocalDate.parse(decoder.decodeString())
}

@Serializable
data class Event(
    val name: String,
    @Serializable(with = LocalDateSerializer::class) val date: LocalDate,
    val createdAt: kotlin.time.Instant,
)

{"name":"release","date":"2026-10-12","createdAt":"2026-10-12T01:02:03Z"}
Event(name=release, date=2026-10-12, createdAt=2026-10-12T01:02:03Z)

"2026/10/12" を読むと、java.time.format.DateTimeParseException: Text '2026/10/12' could not be parsed at index 4 がそのまま出ました。

@Contextual で一か所にまとめる

プロパティごとに with = を書かず、Json の設定で登録する方法です。

@Serializable
data class Holiday(val name: String, @Contextual val date: LocalDate)

val json = Json {
    serializersModule = SerializersModule {
        contextual(LocalDate::class, LocalDateSerializer)
    }
}

{"name":"sports-day","date":"2026-10-12"}

登録していない Json（素の Json）で同じクラスを出力すると、実行時に Serializer for class 'LocalDate' is not found. になりました。 @Contextual は「実行時に Json の設定から探す」という意味なので、使う Json すべてに登録が要ります。

Java の日付の書式は、関連記事「Kotlin 日付と時刻の扱い方 LocalDateのフォーマットと差分計算」で扱っています。

enum と sealed class

enum

enum は名前の文字列で出力されます。@SerialName で JSON 側の値を変えられます。知らない値が来たときは Status does not contain element with name 'archived' になり、coerceInputValues = true と既定値の組み合わせで既定値に置き換えられます（上の表）。enum の基本は、関連記事「Kotlin enum classの使い方 entries・valueOf一覧」で扱っています。

sealed class（ポリモーフィズム）

@Serializable
sealed interface Shape

@Serializable @SerialName("circle")
data class Circle(val radius: Double) : Shape

@Serializable @SerialName("rect")
data class Rect(val w: Double, val h: Double) : Shape

val shapes: List<Shape> = listOf(Circle(1.0), Rect(2.0, 3.0))
Json.encodeToString(shapes)

[{"type":"circle","radius":1.0},{"type":"rect","w":2.0,"h":3.0}]

sealed の親が @Serializable なら、子クラスは自動で登録されます。 型名は "type" というキーで入ります。値は @SerialName の値で、付けなければクラスの完全修飾名です。

変数の型が子クラスのままだと、型名が付きません。 読むときに親の型で受けるなら、書くときも encodeToString<Shape>(…) のように親の型を指定します。

sealed class の基本は、関連記事「Kotlin sealed classの使い方 enumとの違いとwhen網羅」で扱っています。

value class・ジェネリクス・JsonElement

@Serializable @JvmInline
value class UserId(val value: Long)

@Serializable
data class Order(val id: Long, val userId: UserId)

@Serializable
data class Page<T>(val items: List<T>, val total: Int)

Json.encodeToString(Order(1, UserId(42)))
{"id":1,"userId":42}

Json.encodeToString(Page(listOf(User(1, "A")), 1))
{"items":[{"id":1,"name":"A"}],"total":1}

@Serializable の value class は、中身の値だけで出力されます（{"value":42} にはならない）。value class の使い方は、関連記事「Kotlin value classの使い方｜IDの取り違えを型で防ぐ」で扱っています。ジェネリクスのクラスも、decodeFromString<Page<User>>(…) のように型引数を書けば読めました。

クラスを作らずに JSON を扱うときは JsonElement を使います。

val el = Json.parseToJsonElement("""{"user":{"id":7,"name":"Ito"},"tags":["x","y"]}""")
el.jsonObject["user"]!!.jsonObject["name"]!!.jsonPrimitive.content   // Ito
el.jsonObject["user"]!!.jsonObject["id"]!!.jsonPrimitive.int         // 7
el.jsonObject["tags"]!!.jsonArray.size                               // 2

val built = buildJsonObject {
    put("id", 1)
    put("name", "Ito")
    putJsonArray("tags") { add("a"); add("b") }
}
// {"id":1,"name":"Ito","tags":["a","b"]}

Json.decodeFromJsonElement<User>(el.jsonObject["user"]!!)              // User(id=7, name=Ito, ...)

よくあるエラーと原因

エラー文は、v1.11.0 を実行して出たものです（JSON input: の行は省いたものもあります）。

エラー文の at path: $.status は、JSON の中のどこで止まったかを示します。 $ が一番外のオブジェクトで、$.items[0].name のように深くなります。

例外の種類

1.11.0 の CHANGELOG では、JsonDecodingException などが公開され、path・offset などのプロパティを持つようになったとあります。REST API でエラーの場所を返すときに使えます。

エラー文に入力の JSON を出したくないとき

既定では、エラー文の最後に JSON input: {…} として入力が入ります。パスワードなどがログに残るのを避けたいときは、1.11.0 で入った exceptionsWithDebugInfo = false（実験的 API）を使います。実行すると、JSON input: の行が消えました。CHANGELOG では、この動きは安定版になったときに既定になる予定とされています。

よくある質問

Q. Jackson と比べて何が違いますか。 A. kotlinx.serialization はコンパイル時に変換コードを作るので、リフレクションを使いません。Kotlin の既定値・null 許容をそのまま扱え、マルチプラットフォーム（JS・Native）でも動きます。Jackson は Java の型や注釈の資産が多く、Spring の既定です。Jackson の使い方は、関連記事「Jackson ObjectMapperの使い方｜JSON変換・日付・record」で扱っています。

Q. Ktor で使うには？ A. Ktor の ContentNegotiation に json() を登録すると、kotlinx.serialization で JSON を変換します。関連記事「Ktor 入門｜REST APIをJSON・例外処理・テストまで作る」で扱っています。

Q. data class でなくても使えますか。 A. 使えます。kotlinx.serialization のガイドでは、バッキングフィールド（値を入れておく場所）を持つプロパティが対象とされています。計算するだけの get() のプロパティは出力されません。data class の基本は、関連記事「Kotlin data classの使い方｜copy・equalsとclass差」で扱っています。

まとめ

• プラグイン（kotlin("plugin.serialization")）とライブラリの両方を入れる。プラグインが無いと実行時に Serializer for class … is not found
• 既定値と同じ値は出力されない（encodeDefaults = false）。既定値の無いプロパティは JSON に必須
• API のクライアントには ignoreUnknownKeys・explicitNulls = false・coerceInputValues の組み合わせ
• Json は使い回す。毎回作るとプラグインが警告を出した
• 日付は kotlinx-datetime か 自作 KSerializer。java.time.LocalDate はそのままではコンパイルエラー
• sealed は親の型で encodeToString<Shape> すると "type" の型名が付く

参考・出典

確認日はいずれも 2026年10月12日です。

• Kotlin ドキュメント「Serialization」（Get started）：https://kotlinlang.org/docs/serialization-get-started.html
• kotlinx.serialization（GitHub、ソース・ガイド・タグ v1.11.0）：https://github.com/Kotlin/kotlinx.serialization
• kotlinx.serialization CHANGELOG：https://github.com/Kotlin/kotlinx.serialization/blob/master/CHANGELOG.md
• kotlinx.serialization ガイド「JSON features」：https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/json.md
• kotlinx-datetime（GitHub、README・CHANGELOG・タグ v0.8.0）：https://github.com/Kotlin/kotlinx-datetime

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。