Skip to content

JSON要素 ​

Kotlin serialization は、構造レベルで JSON を操作することもサポートしています。 JsonElement API を使用すると、JSON 構造を Kotlin の型や文字列に変換する前に、直接検査、変更、および構築できます。

JsonElement には、コアとなる JSON 構造を表す3つの直接のサブタイプがあります。

  • JsonPrimitive は、文字列、数値、真偽値、および null などのプリミティブな JSON 要素を扱います。null 値は、JsonNull と呼ばれる JsonPrimitive の特別なサブクラスによって表されます。 各 JsonPrimitive はその値の文字列表現を保持しており、JsonPrimitive.content プロパティを通じてアクセスできます。
  • JsonArray は JSON 配列を表します。これは JsonElement 項目の Kotlin List です。
  • JsonObject は JSON オブジェクトを表します。これは String のキーと JsonElement の値を持つ Kotlin Map です。

文字列をJSON要素にパースする ​

文字列を JsonElement にパースすることで、Kotlin の型や文字列に変換する前に JSON 構造を操作できます。

入力を行のデコードやデシリアライズをすることなく JSON 要素ツリーにパースするには、Json.parseToJsonElement() 関数を使用します。

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

fun main() {
    val element = Json.parseToJsonElement("""
        {"name":"kotlinx.serialization","language":"Kotlin"}
    """)
    // JsonElement.toString() は有効なJSON文字列を返します
    println(element)
    // {"name":"kotlinx.serialization","language":"Kotlin"}
}

JSON要素のコンテンツにアクセスする ​

JsonElement API の拡張プロパティを通じて、JSON 要素のコンテンツに直接アクセスできます。 これらの拡張プロパティは、要素を特定のサブタイプにキャストし、要素が期待される JSON 構造を持っていない場合は IllegalArgumentException をスローします。

利用可能な拡張プロパティは以下のとおりです。

同様に、JsonPrimitive には、値を Kotlin のプリミティブ型としてパースするための拡張プロパティがあります。例えば、int、intOrNull、long、longOrNull などです。

構造が既知の JSON データを処理する際に、これらの拡張プロパティをどのように使用できるかの例を以下に示します。

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

fun main() {
    val element = Json.parseToJsonElement("""
        {
            "name": "kotlinx.serialization",
            "forks": [{"votes": 42}, {"votes": 9000}, {}]
        }
    """)
    val sum = element
        // JsonObjectからforksキーにアクセス
        .jsonObject["forks"]!!

        // JsonArrayとして値にアクセスし、各JsonObjectからvotesの値をIntとして合計
        .jsonArray.sumOf { it.jsonObject["votes"]?.jsonPrimitive?.int ?: 0 }
    println(sum)
    // 9042
}

事前に JSON の構造がわからない場合は、要素の型をチェックして、各 JsonElement のサブタイプを明示的に処理できます。 例えば、when 式を使用したヘルパー関数を利用できます。

kotlin
fun processElement(element: JsonElement): String = when (element) {
    is JsonObject -> "JsonObject with keys: ${element.keys}"
    is JsonArray -> "JsonArray with ${element.size} elements"
    is JsonPrimitive -> "JsonPrimitive with content: ${element.content}"
}

JSON要素を作成する ​

特定の JsonElement サブタイプのインスタンスを直接作成できます。

JsonPrimitive を作成するには、JsonPrimitive() 関数を使用します。

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

fun main() {
    // さまざまなKotlinプリミティブからJsonPrimitive値を作成
    val number = JsonPrimitive(42)
    val text = JsonPrimitive("kotlinx.serialization")

    println(number)
    // 42
    println(text)
    // "kotlinx.serialization"
}

JsonArray および JsonObject 要素は、直接コンストラクタを呼び出すか、ビルダー関数を使用して作成できます。

ビルダー関数は、Kotlin 標準ライブラリのコレクションビルダー に似た DSL を提供し、JSON 固有のオーバーロードや内部ビルダー関数を備えています。

以下は、JSON ビルダー DSL の主な機能を示す例です。

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

fun main() {
    val element = buildJsonObject {
        // JsonObjectにシンプルなキー・値のペアを追加
        put("name", "kotlinx.serialization")
        // ownerキーの下にネストされたJsonObjectを追加
        putJsonObject("owner") {
            put("name", "kotlin")
        }
        // 複数のJsonObjectを持つJsonArrayを追加
        putJsonArray("forks") {
            // JsonArrayにJsonObjectを追加
            addJsonObject {
                put("votes", 42)
            }
            addJsonObject {
                put("votes", 9000)
            }
        }
    }
    // 結果のJSON文字列を出力
    println(element)
    // {"name":"kotlinx.serialization","owner":{"name":"kotlin"},"forks":[{"votes":42},{"votes":9000}]}
}

リテラルJSONコンテンツをエンコードする ​

JSON の仕様では数値のサイズや精度に制限はありませんが、JsonPrimitive() 関数を使用して任意のサイズの数値をシリアライズすると、いくつかの問題が発生する可能性があります。

例えば、大きな数値に Double を使用すると、値が切り捨てられて精度が失われる可能性があります。 Kotlin/JVM の BigDecimal を使用すると、精度は保たれますが、JsonPrimitive() はその値を数値としてではなく文字列としてエンコードします。

kotlin
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal

val format = Json { prettyPrint = true }

fun main() {
    val pi = BigDecimal("3.141592653589793238462643383279")
    
    // BigDecimalをDoubleに変換(切り捨てが発生する可能性あり)
    val piJsonDouble = JsonPrimitive(pi.toDouble())
    // BigDecimalをStringに変換(精度は維持されるが、JSONでは文字列として扱われる)
    val piJsonString = JsonPrimitive(pi.toString())
  
    val piObject = buildJsonObject {
        put("pi_double", piJsonDouble)
        put("pi_string", piJsonString)
    }

    println(format.encodeToString(piObject))
    // "pi_double": 3.141592653589793,
    // "pi_string": "3.141592653589793238462643383279"
}

この例では、pi が小数第30位までの数値として定義されているにもかかわらず、生成された JSON はその精度を保持していません。 Double の値は小数第15位までに切り捨てられ、String の値は引用符で囲まれるため、数値ではなく JSON 文字列になってしまいます。

これらの問題を回避するために、JsonUnquotedLiteral() 関数を使用して、この例の pi の文字列値のような、引用符で囲まれていない任意の値をエンコードできます。

kotlin
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal

val format = Json { prettyPrint = true }

fun main() {
    val pi = BigDecimal("3.141592653589793238462643383279")

    // JsonUnquotedLiteral()を使用して生のJSONコンテンツをエンコード
    @OptIn(ExperimentalSerializationApi::class)
    val piJsonLiteral = JsonUnquotedLiteral(pi.toString())

    // DoubleおよびStringに変換
    val piJsonDouble = JsonPrimitive(pi.toDouble())
    val piJsonString = JsonPrimitive(pi.toString())

    val piObject = buildJsonObject {
        put("pi_literal", piJsonLiteral)
        put("pi_double", piJsonDouble)
        put("pi_string", piJsonString)
    }

    // pi_literalは定義された値と正確に一致するようになります
    println(format.encodeToString(piObject))
    // "pi_literal": 3.141592653589793238462643383279,
    // "pi_double": 3.141592653589793,
    // "pi_string": "3.141592653589793238462643383279"
}

pi を BigDecimal にデコードし直すには、JsonPrimitive の文字列コンテンツを抽出します。

kotlin
// シリアライゼーションライブラリから宣言をインポート
import kotlinx.serialization.*
import kotlinx.serialization.json.*
import java.math.BigDecimal

fun main() {
    val piObjectJson = """
          {
              "pi_literal": 3.141592653589793238462643383279
          }
      """.trimIndent()

    // JSON文字列をJsonObjectにデコード
    val piObject: JsonObject = Json.decodeFromString(piObjectJson)

    // JsonPrimitiveから文字列コンテンツを抽出
    val piJsonLiteral = piObject["pi_literal"]!!.jsonPrimitive.content

    // 文字列をBigDecimalに変換
    val pi = BigDecimal(piJsonLiteral)
    // 30桁すべての小数部を保持した状態でデコードされたpiの値を出力
    println(pi)
    // 3.141592653589793238462643383279
}

この例では単純化のために JsonPrimitive を使用しています。より再利用可能なアプローチについては、JSON 構造の変換 を参照してください。

JSONのnullリテラル ​

不整合な状態の作成を防ぐため、JsonUnquotedLiteral() 関数で文字列 "null" をエンコードすることはできません。 エンコードしようとすると、例外がスローされます。

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

@OptIn(ExperimentalSerializationApi::class)
fun main() {
    JsonUnquotedLiteral("null")
    // Exception in thread "main" kotlinx.serialization.json.internal.JsonEncodingException
}

JSON の null リテラル値を表すには、JsonNull を使用します。

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

fun main() {
    val possiblyNull = JsonNull
  
    println(possiblyNull)
    // null
}

JSON要素をデコードする ​

JsonElement クラスのインスタンスをシリアライズ可能なオブジェクトにデコードするには、Json.decodeFromJsonElement() 関数を使用します。

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

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

fun main() {
    val element = buildJsonObject {
        put("name", "kotlinx.serialization")
        put("language", "Kotlin")
    }

    // JsonElementをProjectオブジェクトにデコード
    val data = Json.decodeFromJsonElement<Project>(element)
    println(data)
    // Project(name=kotlinx.serialization, language=Kotlin)
}

次のステップ ​