JSON → Kotlin データクラス

型マッピング

• 文字列 → String、真偽値 → Boolean
• −2,147,483,648〜2,147,483,647 の整数 → Int、それより大きい → Long、Long の範囲外 → Double
• 小数点か指数を含む数値（9.5、19.0、1e3）→ Double
• 配列 → List<T>。Int・Long・Double が混ざると最も広い型、それ以外の混在と空配列は List<JsonElement>
• null → Nullable 型、常に null のフィールド → JsonElement?
• ネストしたオブジェクト → 別の data class、空オブジェクト {} → class Name（data class にはプロパティが 1 つ以上必要）

例：snake_case の API レスポンス

snake_case のキー、null のフィールド、Int.MAX_VALUE を超えるカウンター、4.0 と書かれた評価を含む入力：

{"user_id": 1024, "display_name": "Alice", "is_active": true, "last_login": null, "follower_count": 3000000000, "rating": 4.0, "tags": ["admin", "editor"], "address": {"city": "Tokyo", "zip_code": "100-0001"}}

出力：

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.JsonElement

@Serializable
data class RootObject(
  @SerialName("user_id")
  val userId: Int = 0,
  @SerialName("display_name")
  val displayName: String = "",
  @SerialName("is_active")
  val isActive: Boolean = false,
  @SerialName("last_login")
  val lastLogin: JsonElement? = null,
  @SerialName("follower_count")
  val followerCount: Long = 0L,
  val rating: Double = 0.0,
  val tags: List<String> = emptyList(),
  val address: Address = Address()
)

@Serializable
data class Address(
  val city: String = "",
  @SerialName("zip_code")
  val zipCode: String = ""
)

camelCase 名が JSON キーと異なるフィールドは @SerialName で元のキーを保持します。キーに使われた Kotlin のキーワード（class、in、fun）はバッククォートで囲みます。last_login はサンプルでは null だけなので JsonElement? になります。タイムスタンプだとわかったら String? に変えてください。

例：オブジェクトの配列

ルートが配列のときは、すべてのオブジェクトを 1 つのクラスにまとめます。price は 2 と 1.5 なので Double になります。一部の要素にしかないキーは Nullable で、既定値は null です。

[{"id": 1, "name": "Pen", "price": 2}, {"id": 2, "name": "Ink", "price": 1.5, "discount": 0.1}]

import kotlinx.serialization.Serializable

@Serializable
data class RootObject(
  val id: Int = 0,
  val name: String = "",
  val price: Double = 0.0,
  val discount: Double? = null
)

ステータス行に List<RootObject> としてデコードするよう表示されます。

例：同じ名前のキー、異なるオブジェクト

フィールドの異なる meta が 2 つあると、クラスも 2 つ生成され、2 つ目には親の名前が前に付きます。

{"order": {"id": 7, "meta": {"source": "web"}}, "payment": {"meta": {"method": "card", "last4": "4242"}}}

import kotlinx.serialization.Serializable

@Serializable
data class RootObject(
  val order: Order = Order(),
  val payment: Payment = Payment()
)

@Serializable
data class Order(
  val id: Int = 0,
  val meta: Meta = Meta()
)

@Serializable
data class Meta(
  val source: String = ""
)

@Serializable
data class Payment(
  val meta: PaymentMeta = PaymentMeta()
)

@Serializable
data class PaymentMeta(
  val method: String = "",
  val last4: String = ""
)

デコード

ビルド設定にシリアライゼーションプラグインと JSON ライブラリを追加し（Kotlin のシリアライゼーションガイド参照）、次のようにデコードします。

import kotlinx.serialization.json.Json

val user = Json.decodeFromString<RootObject>(body)
val items = Json.decodeFromString<List<RootObject>>(arrayBody)

// サンプルにないキーを許容する
val lenient = Json { ignoreUnknownKeys = true }

既定の Json はクラスにないキーをエラーにします。このページの例はすべて Kotlin 2.4.20 と kotlinx.serialization 1.11.0 でコンパイルし、既定の設定でデコードできることを確認しています。

制限事項

• 型は 1 つのサンプルだけから決まります。サンプルで小さい ID は Int になるので、本番の ID が 2,147,483,647 を超えるなら Long に直してください。
• ブラウザーは JSON の数値を 64 ビット浮動小数点で読むため、9,007,199,254,740,991 を超える整数は型を決める前に桁が落ちます。型は Long のままですが、範囲は手で確認してください。
• 19.0 を小数と判定できるのは、JSON.parse にソーステキストを渡すブラウザー（Chrome 114+、Firefox 135+、Safari 18.4+）だけです。古いブラウザーでは Int になります。
• JsonElement のフィールドは Json 形式でだけ使え、CBOR や ProtoBuf では使えません。
• 日付は String のままです。JSON に日付型はないので、デコード後に解析するかカスタムシリアライザーを追加してください。
• すべてのプロパティに既定値があるため、キーが欠けても黙って既定値になります。必須のキーは既定値を削除してください。