Skip to content

クラスのシリアライズ ​

@Serializable アノテーションは、バッキングフィールドを持つすべてのクラスプロパティのデフォルトのシリアライズを有効にします。 この動作は、特定のニーズに合わせてカスタマイズできます。 このページでは、さまざまなシリアライズ技術を取り上げ、どのプロパティをシリアライズするかを指定する方法や、シリアライズ処理を管理する方法について説明します。

始める前に、必要なライブラリの依存関係をインポートしていることを確認してください。

@Serializable アノテーション ​

@Serializable アノテーションを使用すると、クラスプロパティの自動シリアライズが可能になり、JSON などのフォーマットとの間でクラスを相互に変換できるようになります。

Kotlin では、バッキングフィールドを持つプロパティのみがシリアライズされます:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
class Project(
    // バッキングフィールドを持つプロパティ – シリアライズされる
    var name: String
) {
    // バッキングフィールドを持つプロパティ – シリアライズされる
    var stars: Int = 0

    // バッキングフィールドを持たないゲッターのみのプロパティ - シリアライズされない
    val path: String
        get() = "kotlin/$name"

    // 委譲プロパティ - シリアライズされない
    var id by ::name
}

fun main() {
    val data = Project("kotlinx.serialization").apply { stars = 9000 }
    // name プロパティと stars プロパティのみを出力
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization","stars":9000}
}

クラス参照のシリアライズ ​

@Serializable でアノテーションが付けられたクラスは、他のクラスを参照するプロパティを含めることができます。 参照される側のクラスも、@Serializable でアノテーションが付けられている必要があります。 JSON にエンコードすると、ネストされた JSON オブジェクトになります:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
// owner プロパティは別のシリアライズ可能なクラス User を参照
class Project(val name: String, val owner: User)

// 参照されるクラスにも @Serializable アノテーションが必要
@Serializable
class User(val name: String)

fun main() {
    val owner = User("kotlin")
    val data = Project("kotlinx.serialization", owner)
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization","owner":{"name":"kotlin"}}
}

シリアライズ可能でないクラスを参照するには、対応するプロパティに @Transient アノテーションを付与するか、それらのクラス用のカスタムシリアライザーを提供してください。

重複するオブジェクト参照のシリアライズ ​

Kotlin のシリアライズは、プレーンなデータのエンコードおよびデコードを目的として設計されています。重複したオブジェクト参照を含む任意のオブジェクトグラフの再構築はサポートしていません。 例えば、同じインスタンスを 2 回参照するオブジェクトをシリアライズすると、そのインスタンスは 2 回エンコードされます:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
class Project(val name: String, val owner: User, val maintainer: User)

@Serializable
class User(val name: String)

fun main() {
    val owner = User("kotlin")
    // owner を 2 回参照
    val data = Project("kotlinx.serialization", owner, owner)
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization","owner":{"name":"kotlin"},"maintainer":{"name":"kotlin"}}
}

循環構造をシリアライズしようとすると、スタックオーバーフローが発生します。 参照をシリアライズから除外するには、@Transient アノテーションを使用してください。

ジェネリッククラスのシリアライズ ​

Kotlin のジェネリッククラスは型の多態性(型ポリモーフィズム)をサポートしており、これはコンパイル時に Kotlin のシリアライズによって強制されます。例えば、シリアライズ可能なジェネリッククラス Payload<T> を考えてみましょう:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
// Payload<T> クラスは、Int のような組み込み型や、
// Repository のような @Serializable が付いたユーザー定義型で使用できます
class Payload<T>(val value: T)

@Serializable
data class Repository(val name: String, val language: String)

@Serializable
class BackupData(
    val issueCount: Payload<Int>,
    val mainRepo: Payload<Repository>
)

fun main() {
    val backup = BackupData(
        Payload(42),
        Payload(Repository("kotlinx.serialization", "Kotlin"))
    )
    println(Json.encodeToString(backup))
    // {"issueCount":{"value":42},"mainRepo":{"value":{"name":"kotlinx.serialization","language":"Kotlin"}}}
}

Box<T> のようなジェネリッククラスをシリアライズする場合、JSON の出力はコンパイル時に T に指定した実際の型に依存します。 その型がシリアライズ可能でない場合、コンパイルエラーが発生します。

オプショナルなプロパティ ​

_デフォルト値_を持つプロパティは、デシリアライズ時にはオプショナル(省略可能)となり、フォーマットの設定によってはシリアライズ時にスキップできます。 例えば、デフォルトの JSON 設定では、デフォルト値のエンコードがスキップされます。

オプショナルなプロパティにデフォルト値を設定する ​

Kotlin では、入力内にすべてのプロパティが存在する場合にのみオブジェクトをデシリアライズできます。 シリアライズにおいてプロパティをオプショナルにするには、入力に値が指定されていない場合に使用されるデフォルト値を設定します:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
// オプショナルな language プロパティにデフォルト値を設定
data class Project(val name: String, val language: String = "Kotlin")

fun main() {
    val data = Json.decodeFromString<Project>("""
        {"name":"kotlinx.serialization"}
    """)
    println(data)
    // Project(name=kotlinx.serialization, language=Kotlin)
}

null 許容プロパティのシリアライズ ​

Kotlin のシリアライズは、null 許容プロパティをネイティブにサポートしています。 他のデフォルト値と同様に、null 値は JSON 出力にエンコードされません:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
// null のデフォルト値を持つ null 許容プロパティ renamedTo を備えたクラスを定義
class Project(val name: String, val renamedTo: String? = null)

fun main() {
    val data = Project("kotlinx.serialization")
    // 値が null であるため、renamedTo プロパティはエンコードされない
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization"}
}

さらに、Kotlin の null 安全性はデシリアライズ時にも強力に適用されます。 JSON オブジェクトに非 null プロパティに対する null 値が含まれている場合、そのプロパティにデフォルト値があったとしても例外がスローされます:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
data class Project(val name: String, val language: String = "Kotlin")

fun main() {
    val data = Json.decodeFromString<Project>("""
        {"name":"kotlinx.serialization","language":null}
    """)
    println(data)
    // JsonDecodingException
}

サードパーティの JSON からの null 値を処理する必要がある場合は、それらをデフォルト値に強制変換(coerce)できます。

また、explicitNulls プロパティを使用して、エンコードされた JSON から明示的な null 値を省略することもできます。

オプショナルなプロパティのイニシャライザ ​

シリアライズの入力にオプショナルなプロパティの値が含まれている場合、そのプロパティのイニシャライザは呼び出されません。 そのため、プロパティのイニシャライザ内で副作用を持つコードを使用することは避けてください。

例を以下に示します:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

fun computeLanguage(): String {
    println("Computing")
    return "Kotlin"
}

@Serializable
// 入力に language が含まれている場合はイニシャライザをスキップ
data class Project(val name: String, val language: String = computeLanguage())

fun main() {
    val data = Json.decodeFromString<Project>("""
        {"name":"kotlinx.serialization","language":"Java"}
    """)
    println(data)
    // Project(name=kotlinx.serialization, language=Java)
}

この例では、入力で language プロパティが指定されているため、出力に Computing という文字列は出力されません。

@EncodeDefault でデフォルトプロパティのシリアライズを管理する ​

デフォルトでは、JSON シリアライズはデフォルト値を持つプロパティを除外します。 これにより、シリアライズされるデータのサイズが削減され、余計な煩雑さを回避できます。

以下は、language プロパティの値がデフォルト値と等しいために出力から除外される例です:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
data class Project(val name: String, val language: String = "Kotlin")

fun main() {
    val data = Project("kotlinx.serialization")
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization"}
}

デフォルトですべてのプロパティのデフォルト値をエンコードするように Json インスタンスを設定できます。

値やフォーマット設定に関係なく、プロパティを常にシリアライズするには、@EncodeDefault アノテーションを使用します。 あるいは、EncodeDefault.Mode パラメータを設定してこの動作を変更することもできます。

language プロパティがシリアライズされた出力に常に含まれ、一方で projects プロパティが空のリストである場合に除外される例を見てみましょう:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlinx.serialization.EncodeDefault.Mode.NEVER

@Serializable
data class Project(
    val name: String,
    // デフォルト値 "Kotlin" を持っている場合でも、
    // シリアライズされた出力に language プロパティを常に含める
    @EncodeDefault val language: String = "Kotlin"
)

@Serializable
data class User(
    val name: String,
    // デフォルト値がある場合でも、空のリストのときは projects を除外する
    @EncodeDefault(NEVER) val projects: List<Project> = emptyList()
)

fun main() {
    val adminUser = User("Alice", listOf(Project("kotlinx.serialization")))
    val guestUser = User("Bob")
    // projects に値が含まれているためシリアライズされる
    // language は常にシリアライズされる
    println(Json.encodeToString(adminUser))
    // {"name":"Alice","projects":[{"name":"kotlinx.serialization","language":"Kotlin"}]}

    // projects は空のリストであり、EncodeDefault.Mode が NEVER に
    // 設定されているため除外され、シリアライズされない
    println(Json.encodeToString(guestUser))
    // {"name":"Bob"}
}

@Required アノテーションでプロパティを必須にする ​

プロパティに @Required アノテーションを付けると、入力内でそのプロパティが必須になります。 これにより、プロパティにデフォルト値がある場合であっても、入力にそのプロパティが含まれていることが強制されます:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlinx.serialization.Required

@Serializable
// language プロパティを必須としてマーク
data class Project(val name: String, @Required val language: String = "Kotlin")

fun main() {
    val data = Json.decodeFromString<Project>("""
        {"name":"kotlinx.serialization"}
    """)
    println(data)
    // MissingFieldException
}

クラスのシリアライズをカスタマイズする ​

Kotlin のシリアライズには、クラスがどのようにシリアライズされるかを変更するための方法がいくつか用意されています。 このセクションでは、プロパティ名のカスタマイズや、プロパティのシリアライズ対象の制御などのテクニックを取り上げます。

シリアル名のカスタマイズ ​

デフォルトでは、JSON などのシリアライズ出力におけるプロパティ名は、ソースコード内の名前と一致します。

_シリアル名_と呼ばれるこれらの名前は、@SerialName アノテーションを使ってカスタマイズできます。 シリアライズされた出力でプロパティ名をよりわかりやすく表現したい場合などに使用します:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
// @SerialName を使用して lang プロパティの名前を language に変更
class Project(val name: String, @SerialName("language") val lang: String)

fun main() {
    val data = Project("kotlinx.serialization", "Kotlin")
    // JSON 出力によりわかりやすいプロパティ名を出力
    println(Json.encodeToString(data))
    // {"name":"kotlinx.serialization","language":"Kotlin"}
}

シリアライズ用のコンストラクタプロパティを定義する ​

@Serializable でアノテーションが付けられたクラスは、プライマリコンストラクタのすべてのパラメータをプロパティとして宣言する必要があります。

プロパティに値を代入する前に追加の初期化ロジックを実行する必要がある場合は、セカンダリコンストラクタを使用します。 プライマリコンストラクタは private のままにしてプロパティの初期化を処理させることができます。

セカンダリコンストラクタが文字列を 2 つの値にパースし、それがシリアライズのためにプライマリコンストラクタに渡される例を以下に示します:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
class Project private constructor(val owner: String, val name: String) {
    // path 文字列を使用して Project オブジェクトを作成
    constructor(path: String) : this(
        owner = path.substringBefore('/'),
        name = path.substringAfter('/')
    )

    val path: String
        get() = "$owner/$name"
}
fun main() {
    println(Json.encodeToString(Project("kotlin/kotlinx.serialization")))
    // {"owner":"kotlin","name":"kotlinx.serialization"}
}

プライマリコンストラクタでデータを検証する ​

デシリアライズ後、kotlinx.serialization プラグインは、通常のインスタンス生成時と同様にクラスのイニシャライザブロックを実行します。 これにより、コンストラクタパラメータを検証し、デシリアライズ時に無効なデータを拒否できます。

例を以下に示します:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*

@Serializable
class Project(val name: String) {
    // name が空でないことを検証
    init {
        require(name.isNotEmpty()) { "name cannot be empty" }
    }
}

fun main() {
    val data = Json.decodeFromString<Project>("""
        {"name":""}
    """)
    println(data)
    // Exception in thread "main" java.lang.IllegalArgumentException: name cannot be empty
}

@Transient アノテーションでプロパティを除外する ​

@Transient アノテーションを使用すると、プロパティをシリアライズから除外できます。 トランジェントなプロパティにはデフォルト値が必要です。

入力内でトランジェントなプロパティの値を明示的に指定した場合、それがデフォルト値と一致していたとしても JsonDecodingException がスローされます:

kotlin
// シリアライズライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.Transient
import kotlinx.serialization.json.*

@Serializable
// language プロパティをシリアライズから除外
data class Project(val name: String, @Transient val language: String = "Kotlin")

fun main() {
    // 入力がデフォルト値と一致していても例外をスローする
    val data = Json.decodeFromString<Project>("""
        {"name":"kotlinx.serialization","language":"Kotlin"}
    """)
    println(data)
    // JsonDecodingException
}

@Transient アノテーションが付けられたものを含む、JSON 内の未知のキーによる例外を回避するには、ignoreUnknownKeys 設定プロパティを有効にします。 詳細については、未知のキーを無視するのセクションを参照してください。

次のステップ ​

  • より複雑な JSON シリアライズのシナリオについては、JSON シリアライズの概要を参照してください。
  • 生成されたシリアライザーの取得、カスタムシリアライザーの作成、およびシリアライザーの適用方法については、シリアライザーの作成と使用を参照してください。