Add kotlin.time.Instant serializers

core/api/kotlinx-serialization-core.api

@@ -202,9 +202,19 @@ public final class kotlinx/serialization/builtins/BuiltinSerializersKt {
 	public static final fun serializer (Lkotlin/jvm/internal/ShortCompanionObject;)Lkotlinx/serialization/KSerializer;
 	public static final fun serializer (Lkotlin/jvm/internal/StringCompanionObject;)Lkotlinx/serialization/KSerializer;
 	public static final fun serializer (Lkotlin/time/Duration$Companion;)Lkotlinx/serialization/KSerializer;
+	public static final fun serializer (Lkotlin/time/Instant$Companion;)Lkotlinx/serialization/KSerializer;
 	public static final fun serializer (Lkotlin/uuid/Uuid$Companion;)Lkotlinx/serialization/KSerializer;
 }
 
+public final class kotlinx/serialization/builtins/InstantComponentSerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lkotlinx/serialization/builtins/InstantComponentSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlin/time/Instant;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlin/time/Instant;)V
+}
+
 public final class kotlinx/serialization/builtins/LongAsStringSerializer : kotlinx/serialization/KSerializer {
 	public static final field INSTANCE Lkotlinx/serialization/builtins/LongAsStringSerializer;
 	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Long;
@@ -795,6 +805,15 @@ public final class kotlinx/serialization/internal/InlineClassDescriptorKt {
 	public static final fun InlinePrimitiveDescriptor (Ljava/lang/String;Lkotlinx/serialization/KSerializer;)Lkotlinx/serialization/descriptors/SerialDescriptor;
 }
 
+public final class kotlinx/serialization/internal/InstantSerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lkotlinx/serialization/internal/InstantSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlin/time/Instant;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlin/time/Instant;)V
+}
+
 public final class kotlinx/serialization/internal/IntArrayBuilder : kotlinx/serialization/internal/PrimitiveArrayBuilder {
 	public synthetic fun build$kotlinx_serialization_core ()Ljava/lang/Object;
 }

core/api/kotlinx-serialization-core.klib.api

@@ -890,6 +890,14 @@ sealed class kotlinx.serialization.modules/SerializersModule { // kotlinx.serial
     final fun <#A1: kotlin/Any> getContextual(kotlin.reflect/KClass<#A1>): kotlinx.serialization/KSerializer<#A1>? // kotlinx.serialization.modules/SerializersModule.getContextual|getContextual(kotlin.reflect.KClass<0:0>){0§<kotlin.Any>}[0]
 }
 
+final object kotlinx.serialization.builtins/InstantComponentSerializer : kotlinx.serialization/KSerializer<kotlin.time/Instant> { // kotlinx.serialization.builtins/InstantComponentSerializer|null[0]
+    final val descriptor // kotlinx.serialization.builtins/InstantComponentSerializer.descriptor|{}descriptor[0]
+        final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.builtins/InstantComponentSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
+
+    final fun deserialize(kotlinx.serialization.encoding/Decoder): kotlin.time/Instant // kotlinx.serialization.builtins/InstantComponentSerializer.deserialize|deserialize(kotlinx.serialization.encoding.Decoder){}[0]
+    final fun serialize(kotlinx.serialization.encoding/Encoder, kotlin.time/Instant) // kotlinx.serialization.builtins/InstantComponentSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlin.time.Instant){}[0]
+}
+
 final object kotlinx.serialization.builtins/LongAsStringSerializer : kotlinx.serialization/KSerializer<kotlin/Long> { // kotlinx.serialization.builtins/LongAsStringSerializer|null[0]
     final val descriptor // kotlinx.serialization.builtins/LongAsStringSerializer.descriptor|{}descriptor[0]
         final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.builtins/LongAsStringSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
@@ -956,6 +964,14 @@ final object kotlinx.serialization.internal/FloatSerializer : kotlinx.serializat
     final fun serialize(kotlinx.serialization.encoding/Encoder, kotlin/Float) // kotlinx.serialization.internal/FloatSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlin.Float){}[0]
 }
 
+final object kotlinx.serialization.internal/InstantSerializer : kotlinx.serialization/KSerializer<kotlin.time/Instant> { // kotlinx.serialization.internal/InstantSerializer|null[0]
+    final val descriptor // kotlinx.serialization.internal/InstantSerializer.descriptor|{}descriptor[0]
+        final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.internal/InstantSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
+
+    final fun deserialize(kotlinx.serialization.encoding/Decoder): kotlin.time/Instant // kotlinx.serialization.internal/InstantSerializer.deserialize|deserialize(kotlinx.serialization.encoding.Decoder){}[0]
+    final fun serialize(kotlinx.serialization.encoding/Encoder, kotlin.time/Instant) // kotlinx.serialization.internal/InstantSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlin.time.Instant){}[0]
+}
+
 final object kotlinx.serialization.internal/IntArraySerializer : kotlinx.serialization.internal/PrimitiveArraySerializer<kotlin/Int, kotlin/IntArray, kotlinx.serialization.internal/IntArrayBuilder>, kotlinx.serialization/KSerializer<kotlin/IntArray> // kotlinx.serialization.internal/IntArraySerializer|null[0]
 
 final object kotlinx.serialization.internal/IntSerializer : kotlinx.serialization/KSerializer<kotlin/Int> { // kotlinx.serialization.internal/IntSerializer|null[0]
@@ -1074,6 +1090,7 @@ final val kotlinx.serialization.modules/EmptySerializersModule // kotlinx.serial
     final fun <get-EmptySerializersModule>(): kotlinx.serialization.modules/SerializersModule // kotlinx.serialization.modules/EmptySerializersModule.<get-EmptySerializersModule>|<get-EmptySerializersModule>(){}[0]
 
 final fun (kotlin.time/Duration.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin.time/Duration> // kotlinx.serialization.builtins/serializer|[email protected](){}[0]
+final fun (kotlin.time/Instant.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin.time/Instant> // kotlinx.serialization.builtins/serializer|[email protected](){}[0]
 final fun (kotlin.uuid/Uuid.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin.uuid/Uuid> // kotlinx.serialization.builtins/serializer|[email protected](){}[0]
 final fun (kotlin/Boolean.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin/Boolean> // kotlinx.serialization.builtins/serializer|[email protected](){}[0]
 final fun (kotlin/Byte.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin/Byte> // kotlinx.serialization.builtins/serializer|[email protected](){}[0]

core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt

@@ -10,6 +10,8 @@ import kotlinx.serialization.internal.*
 import kotlin.reflect.*
 import kotlinx.serialization.descriptors.*
 import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 import kotlin.uuid.*
 
 /**
@@ -245,12 +247,30 @@ public fun UShort.Companion.serializer(): KSerializer<UShort> = UShortSerializer
 
 /**
  * Returns serializer for [Duration].
- * It is serialized as a string that represents a duration in the ISO-8601-2 format.
+ * It is serialized as a string that represents a duration in the format used by [Duration.toIsoString],
+ * that is, the ISO-8601-2 format.
  *
- * The result of serialization is similar to calling [Duration.toIsoString], for deserialization is [Duration.parseIsoString].
+ * For deserialization, [Duration.parseIsoString] is used.
+ *
+ * @see Duration.toIsoString
+ * @see Duration.parseIsoString
  */
 public fun Duration.Companion.serializer(): KSerializer<Duration> = DurationSerializer
 
+/**
+ * Returns serializer for [Instant].
+ * It is serialized as a string that represents an instant in the format used by [Instant.toString]
+ * and described in ISO-8601-1:2019, 5.4.2.1b).
+ *
+ * Deserialization is case-insensitive.
+ * More details can be found in the documentation of [Instant.toString] and [Instant.parse] functions.
+ *
+ * @see Instant.toString
+ * @see Instant.parse
+ */
+@ExperimentalTime
+public fun Instant.Companion.serializer(): KSerializer<Instant> = InstantSerializer
+
 /**
  * Returns serializer for [Uuid].
  * Serializer operates with a standard UUID string representation, also known as "hex-and-dash" format —

core/commonMain/src/kotlinx/serialization/builtins/InstantComponentSerializer.kt

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2025-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.serialization.builtins
+
+import kotlinx.serialization.*
+import kotlinx.serialization.descriptors.*
+import kotlinx.serialization.encoding.*
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
+
+/**
+ * Serializer that encodes and decodes [Instant] as its second and nanosecond components of the Unix time.
+ *
+ * JSON example: `{"epochSeconds":1607505416,"nanosecondsOfSecond":124000}`.
+ */
+@ExperimentalTime
+public object InstantComponentSerializer : KSerializer<Instant> {
+
+    override val descriptor: SerialDescriptor =
+        buildClassSerialDescriptor("kotlinx.serialization.InstantComponentSerializer") {
+            element<Long>("epochSeconds")
+            element<Long>("nanosecondsOfSecond", isOptional = true)
+        }
+
+    @OptIn(ExperimentalSerializationApi::class)
+    override fun deserialize(decoder: Decoder): Instant =
+        decoder.decodeStructure(descriptor) {
+            var epochSecondsNotSeen = true
+            var epochSeconds: Long = 0
+            var nanosecondsOfSecond = 0
+            while (true) {
+                when (val index = decodeElementIndex(descriptor)) {
+                    0 -> {
+                        epochSecondsNotSeen = false
+                        epochSeconds = decodeLongElement(descriptor, 0)
+                    }
+                    1 -> nanosecondsOfSecond = decodeIntElement(descriptor, 1)
+                    CompositeDecoder.DECODE_DONE -> break
+                    else -> throw SerializationException("Unexpected index: $index")
+                }
+            }
+            if (epochSecondsNotSeen) throw MissingFieldException(
+                missingField = "epochSeconds",
+                serialName = descriptor.serialName
+            )
+            Instant.fromEpochSeconds(epochSeconds, nanosecondsOfSecond)
+        }
+
+    @OptIn(ExperimentalSerializationApi::class)
+    override fun serialize(encoder: Encoder, value: Instant) {
+        encoder.encodeStructure(descriptor) {
+            encodeLongElement(descriptor, 0, value.epochSeconds)
+            if (value.nanosecondsOfSecond != 0) {
+                encodeIntElement(descriptor, 1, value.nanosecondsOfSecond)
+            }
+        }
+    }
+
+}

core/commonMain/src/kotlinx/serialization/internal/BuiltInSerializers.kt

@@ -10,6 +10,8 @@ import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 import kotlin.uuid.*
 
 
@@ -39,6 +41,20 @@ internal object NothingSerializer : KSerializer<Nothing> {
     }
 }
 
+@PublishedApi
+@ExperimentalTime
+internal object InstantSerializer : KSerializer<Instant> {
+    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("kotlin.time.Instant", PrimitiveKind.STRING)
+
+    override fun serialize(encoder: Encoder, value: Instant) {
+        encoder.encodeString(value.toString())
+    }
+
+    override fun deserialize(decoder: Decoder): Instant {
+        return Instant.parse(decoder.decodeString())
+    }
+}
+
 @PublishedApi
 @ExperimentalUuidApi
 internal object UuidSerializer: KSerializer<Uuid> {

core/commonTest/src/kotlinx/serialization/BasicTypesSerializationTest.kt

@@ -10,7 +10,6 @@ import kotlinx.serialization.descriptors.*
 import kotlinx.serialization.encoding.*
 import kotlinx.serialization.encoding.CompositeDecoder.Companion.UNKNOWN_NAME
 import kotlinx.serialization.modules.*
-import kotlinx.serialization.test.*
 import kotlin.test.*
 import kotlin.time.Duration
 

core/jsMain/src/kotlinx/serialization/internal/Platform.kt

@@ -81,7 +81,8 @@ private val KClass<*>.isInterface: Boolean
         return js.asDynamic().`$metadata$`?.kind == "interface"
     }
 
-@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class)
+@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class,
+    ExperimentalTime::class)
 internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     String::class to String.serializer(),
     Char::class to Char.serializer(),
@@ -111,5 +112,6 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     Unit::class to Unit.serializer(),
     Nothing::class to NothingSerializer(),
     Duration::class to Duration.serializer(),
+    Instant::class to Instant.serializer(),
     Uuid::class to Uuid.serializer()
 )

core/jvmMain/src/kotlinx/serialization/internal/Platform.kt

@@ -201,6 +201,9 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = buildMap {
     }
     @OptIn(ExperimentalUuidApi::class)
     loadSafe { put(Uuid::class, Uuid.serializer()) }
+
+    @OptIn(ExperimentalTime::class)
+    loadSafe { put(Instant::class, Instant.serializer()) }
 }
 
 // Reference classes in [block] ignoring any exceptions related to class loading

core/nativeMain/src/kotlinx/serialization/internal/Platform.kt

@@ -75,7 +75,8 @@ private fun <T> arrayOfAnyNulls(size: Int): Array<T> = arrayOfNulls<Any>(size) a
 
 internal actual fun isReferenceArray(rootClass: KClass<Any>): Boolean = rootClass == Array::class
 
-@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class)
+@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class,
+    ExperimentalTime::class)
 internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     String::class to String.serializer(),
     Char::class to Char.serializer(),
@@ -105,5 +106,6 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     Unit::class to Unit.serializer(),
     Nothing::class to NothingSerializer(),
     Duration::class to Duration.serializer(),
+    Instant::class to Instant.serializer(),
     Uuid::class to Uuid.serializer()
 )

core/wasmMain/src/kotlinx/serialization/internal/Platform.kt

@@ -65,7 +65,8 @@ internal actual fun <T : Any, E : T?> ArrayList<E>.toNativeArrayImpl(eClass: KCl
 
 internal actual fun isReferenceArray(rootClass: KClass<Any>): Boolean = rootClass == Array::class
 
-@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class)
+@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class,
+    ExperimentalTime::class)
 internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     String::class to String.serializer(),
     Char::class to Char.serializer(),
@@ -95,5 +96,6 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     Unit::class to Unit.serializer(),
     Nothing::class to NothingSerializer(),
     Duration::class to Duration.serializer(),
+    Instant::class to Instant.serializer(),
     Uuid::class to Uuid.serializer()
 )

formats/json-tests/commonTest/src/kotlinx/serialization/InstantSerializationTest.kt

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2025-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.serialization
+
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+import kotlinx.serialization.builtins.*
+import kotlin.time.*
+import kotlin.test.*
+import kotlin.reflect.typeOf
+
+@OptIn(ExperimentalTime::class)
+class InstantSerializationTest: JsonTestBase() {
+    private fun iso8601Serialization(serializer: KSerializer<Instant>) {
+        for ((instant, json) in listOf(
+            Pair(Instant.fromEpochSeconds(1607505416, 124000),
+                "\"2020-12-09T09:16:56.000124Z\""),
+            Pair(Instant.fromEpochSeconds(-1607505416, -124000),
+                "\"1919-01-23T14:43:03.999876Z\""),
+            Pair(Instant.fromEpochSeconds(987654321, 123456789),
+                "\"2001-04-19T04:25:21.123456789Z\""),
+            Pair(Instant.fromEpochSeconds(987654321, 0),
+                "\"2001-04-19T04:25:21Z\""),
+        )) {
+            assertJsonFormAndRestored(serializer, instant, json)
+        }
+        for ((instant, json) in listOf(
+            Pair(Instant.fromEpochSeconds(987654321, 123456789),
+                "\"2001-04-19T07:55:21.123456789+03:30\""),
+            Pair(Instant.fromEpochSeconds(987654321, 123456789),
+                "\"2001-04-19T00:55:21.123456789-03:30\""),
+        )) {
+            assertRestoredFromJsonForm(serializer, json, instant)
+        }
+    }
+
+    private fun componentSerialization(serializer: KSerializer<Instant>) {
+        for ((instant, json) in listOf(
+            Pair(Instant.fromEpochSeconds(1607505416, 124000),
+                "{\"epochSeconds\":1607505416,\"nanosecondsOfSecond\":124000}"),
+            Pair(Instant.fromEpochSeconds(-1607505416, -124000),
+                "{\"epochSeconds\":-1607505417,\"nanosecondsOfSecond\":999876000}"),
+            Pair(Instant.fromEpochSeconds(987654321, 123456789),
+                "{\"epochSeconds\":987654321,\"nanosecondsOfSecond\":123456789}"),
+            Pair(Instant.fromEpochSeconds(987654321, 0),
+                "{\"epochSeconds\":987654321}"),
+        )) {
+            assertJsonFormAndRestored(serializer, instant, json)
+        }
+        // check that having a `"nanosecondsOfSecond": 0` field doesn't break deserialization
+        assertEquals(Instant.fromEpochSeconds(987654321, 0),
+            Json.decodeFromString(serializer,
+                "{\"epochSeconds\":987654321,\"nanosecondsOfSecond\":0}"))
+        // "epochSeconds" should always be present
+        assertFailsWith<SerializationException> { Json.decodeFromString(serializer, "{}") }
+        assertFailsWith<SerializationException> { Json.decodeFromString(serializer, "{\"nanosecondsOfSecond\":3}") }
+    }
+
+    @Test
+    fun testIso8601Serialization() {
+        iso8601Serialization(Instant.serializer())
+    }
+
+    @Test
+    fun testComponentSerialization() {
+        componentSerialization(InstantComponentSerializer)
+    }
+
+    @Test
+    fun testDefaultSerializers() {
+        // should be the same as the ISO 8601
+        @Suppress("UNCHECKED_CAST")
+        iso8601Serialization(serializer(typeOf<Instant>()) as KSerializer<Instant>)
+        // iso8601Serialization(serializer())  TODO: uncomment when the compiler adds KT-75759
+    }
+}

formats/json-tests/commonTest/src/kotlinx/serialization/json/JsonTestBase.kt

@@ -190,4 +190,15 @@ abstract class JsonTestBase {
             assertTrue("Failed with streaming = $jsonTestingMode\n\tsource value =$data\n\tdeserialized value=$deserialized") { check(data, deserialized) }
         }
     }
+
+    internal fun <T> assertRestoredFromJsonForm(
+        serializer: KSerializer<T>,
+        jsonForm: String,
+        expected: T,
+    ) {
+        parametrizedTest { jsonTestingMode ->
+            val deserialized: T = Json.decodeFromString(serializer, jsonForm, jsonTestingMode)
+            assertEquals(expected, deserialized, "Failed with streaming = $jsonTestingMode")
+        }
+    }
 }

gradle.properties

@@ -23,5 +23,3 @@ org.gradle.kotlin.dsl.allWarningsAsErrors=true
 kotlin.native.distribution.type=prebuilt
 
 org.gradle.jvmargs="-XX:+HeapDumpOnOutOfMemoryError"
-
-org.jetbrains.dokka.experimental.tryK2=true

gradle/libs.versions.toml

@@ -1,7 +1,7 @@
 [versions]
 kotlin = "2.1.20"
 kover = "0.8.2"
-dokka = "2.0.0-Beta"
+dokka = "2.0.0"
 knit = "0.5.0"
 bcv = "0.16.2"
 animalsniffer = "1.7.1"