From 56ec279dcf647acdf5220270a14aa1176e0202cf Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Thu, 18 Sep 2025 15:07:15 +0200
Subject: [PATCH 1/7] feat: adding the serialize built in types page

---
 .../serialization-serialize-builtin-types.md  | 378 ++++++++++++++++++
 1 file changed, 378 insertions(+)
 create mode 100644 docs-website/topics/serialization-serialize-builtin-types.md

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
new file mode 100644
index 000000000..9b4362bb4
--- /dev/null
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -0,0 +1,378 @@
+[//]: # (title: Serialize built-in types)
+
+The Kotlin serialization library supports various built-in types, including basic types such as primitives and strings, composite types, and several standard library classes.
+The following sections describe these types in detail and provide examples of how to serialize them.
+
+## Basic types
+
+Kotlin serialization provides built-in serializers for types that are represented as a single value in serialized data.
+This includes, primitives, strings, and enums.
+
+For example, here’s how you can serialize a `Long` type:
+
+```kotlin
+// Imports the necessary library declarations
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Data(val signature: Long)
+
+fun main() {
+    val data = Data(0x1CAFE2FEED0BABE0)
+    println(Json.encodeToString(data))
+    // {"signature":2067120338512882656}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+### Numbers
+
+You can serialize all Kotlin number types, including integers and floating-point numbers, using their natural JSON representations:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+import kotlin.math.PI
+
+//sampleStart
+@Serializable
+class Data(
+    val answer: Int,
+    val pi: Double
+)                     
+
+fun main() {
+    val data = Data(42, PI)
+    println(Json.encodeToString(data))
+    // {"answer":42,"pi":3.141592653589793}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+### Long numbers as strings
+
+When you serialize Kotlin `Long` values to JSON, JavaScript's native number type can't represent the full range of a Kotlin `Long` type,
+leading to precision loss.
+
+Kotlin/JS handles these large `Long` numbers correctly, but JavaScript's native methods don't.
+A common workaround is to represent long numbers with full precision using the JSON string type.
+Kotlin Serialization supports this approach with [`LongAsStringSerializer`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.builtins/-long-as-string-serializer/).
+To apply it to a `Long` property, use the `@Serializable` annotation:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.builtins.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Data(
+    @Serializable(with=LongAsStringSerializer::class)
+    val signature: Long
+)
+
+fun main() {
+    val data = Data(0x1CAFE2FEED0BABE0)
+    println(Json.encodeToString(data))
+    // {"signature":"2067120338512882656"}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+> You can also specify serializers like `LongAsStringSerializer` for all properties in a file.
+> For more information, see [Specify serializers for a file](third-party-classes.md#specify-serializers-for-a-file).
+>
+{style="tip"}
+
+### Enum classes
+
+All `enum` classes are serializable by default without the `@Serializable` annotation.
+When serialized in JSON, an `enum` is encoded as a string:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+// The @Serializable annotation isn't required for enum classes
+enum class Status { SUPPORTED }
+
+@Serializable
+class Project(val name: String, val status: Status) 
+
+fun main() {
+    val data = Project("kotlinx.serialization", Status.SUPPORTED)
+    println(Json.encodeToString(data))
+    // {"name":"kotlinx.serialization","status":"SUPPORTED"}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+> On Kotlin/JS and Kotlin/Native, you must use the `@Serializable` annotation for an `enum` class to use as a root object,
+> such as in `encodeToString<Status>(Status.SUPPORTED)`.
+>
+{style="note"}
+
+#### Customize serial names of enum entries
+
+> For more information on customizing serial names, see [Customize serial names](serialization-customization-options.md#customize-serial-names).
+>
+{style="tip"}
+
+To customize the serial names of enum entries, use the `@SerialName` annotation and mark the enum class with `@Serializable`:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+// Requires the @Serializable annotation because of @SerialName
+@Serializable
+enum class Status { @SerialName("maintained") SUPPORTED }
+
+@Serializable
+class Project(val name: String, val status: Status) 
+
+fun main() {
+    val data = Project("kotlinx.serialization", Status.SUPPORTED)
+    println(Json.encodeToString(data))
+    // {"name":"kotlinx.serialization","status":"maintained"}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+## Composite types
+
+Kotlin Serialization supports several composite types from the standard library, but some classes,
+such as ranges and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class aren't supported yet.
+
+### Pair and triple
+
+You can serialize the [`Pair`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-pair/) and [`Triple`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-triple/) classes from the Kotlin standard library:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Project(val name: String)
+
+fun main() {
+    val pair = 1 to Project("kotlinx.serialization")
+    println(Json.encodeToString(pair))
+    // {"first":1,"second":{"name":"kotlinx.serialization"}}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+### Collections
+
+Kotlin Serialization supports collection types such as [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
+Lists and sets are serialized as JSON arrays, and maps are represented as JSON objects.
+
+#### Serialize lists
+
+Kotlin Serialization serializes [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/) types as JSON arrays.
+Here’s an example with a list of classes:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Project(val name: String)
+
+fun main() {
+    val list = listOf(
+        Project("kotlinx.serialization"),
+        Project("kotlinx.coroutines")    
+    )
+    println(Json.encodeToString(list))
+    // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+#### Serialize sets
+
+[`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/) types are serialized as JSON arrays, just like [`List` types](#serialize-lists):
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Project(val name: String)
+
+fun main() {
+    val set = setOf(
+        Project("kotlinx.serialization"),
+        Project("kotlinx.coroutines")    
+    )
+    println(Json.encodeToString(set))
+    // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+#### Serialize maps
+
+Kotlin serialization supports [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/) types with primitive or enum keys:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Project(val name: String)
+
+fun main() {
+    // Creates a map with Int keys
+    val map = mapOf(
+        1 to Project("kotlinx.serialization"),
+        2 to Project("kotlinx.coroutines")    
+    )
+    println(Json.encodeToString(map))
+    // {"1":{"name":"kotlinx.serialization"},"2":{"name":"kotlinx.coroutines"}}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+In JSON, maps are represented as objects. Since JSON object keys are always strings, keys are encoded as strings even if they are numbers in Kotlin.
+
+> JSON doesn't natively support complex or composite keys.
+> To encode structured objects as map keys, see [Encode structured map keys](serialization-json-configuration.md#encode-structured-map-keys).
+>
+{style="note"}
+
+#### Deserialization behavior of collections
+
+Kotlin uses the declared type to deserialize JSON.
+For example, a `List` preserves duplicates, while a `Set` enforces uniqueness:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+data class Data(
+    val a: List<Int>,
+    val b: Set<Int>
+)
+
+fun main() {
+    val data = Json.decodeFromString<Data>("""
+        {
+            "a": [42, 42],
+            "b": [42, 42]
+        }
+    """)
+    // Duplicates are removed from data.b because Set enforces unique elements
+    println(data)
+    // Data(a=[42, 42], b=[42])
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+> For more information about collections in Kotlin, see [Collections overview](collections-overview.md).
+>
+{style="tip"}
+
+## Unit and singleton objects
+
+The Kotlin [`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/) type and other singleton objects are serializable.
+A [singleton](object-declarations.md) is a class with only one instance, where the state is defined by the object itself rather than by external properties.
+In JSON, singleton objects are serialized as empty structures:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+object SerializationVersion {
+    val libraryVersion: String = "1.0.0"
+}
+
+fun main() {
+    println(Json.encodeToString(SerializationVersion))
+    // {}
+    println(Json.encodeToString(Unit))
+    // {}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+> You can use serialized singleton objects in [closed polymorphic hierarchies](serialization-polymorphism.md#serialize-objects-in-sealed-hierarchies)
+> to represent cases without additional fields.
+>
+{style="tip"}
+
+## Duration
+
+Kotlin's [`Duration`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.time/-duration/) class is serialized to a JSON string using the ISO-8601-2 format:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+import kotlin.time.*
+
+//sampleStart
+fun main() {
+    val duration = 1000.toDuration(DurationUnit.SECONDS)
+    println(Json.encodeToString(duration))
+    // "PT16M40S"
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+## Nothing
+
+The [`Nothing`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-nothing.html) type is serializable by default.
+It has no instances, so encoding or decoding it throws an exception.
+Use `Nothing` when a type is syntactically required, but not involved in serialization, like in [polymorphic classes with generic base types](serialization-polymorphism.md#serialize-polymorphic-types-with-generic-base-types):
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.builtins.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+sealed class ParametrizedParent<out R> {
+    @Serializable
+    data class ChildWithoutParameter(val value: Int) : ParametrizedParent<Nothing>()
+}
+
+fun main() {
+    println(Json.encodeToString(ParametrizedParent.ChildWithoutParameter(42)))
+    // {"value":42}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+## What's next
+
+* Dive into the [Serialize classes](serialization-customization-options.md) section to learn how to serialize classes and how to modify the default behavior of the `@Serializable` annotation.
+* To explore more complex JSON serialization scenarios, see [JSON serialization overview](configure-json-serialization.md).
+* Learn more about polymorphism and serializing different types through a shared base in [Serialize polymorphic classes](serialization-polymorphism.md).

From a763a22124324f9cc508a4ecb1d0317802049057 Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Mon, 20 Oct 2025 10:15:53 +0200
Subject: [PATCH 2/7] update: implementing first round of review comments

---
 .../serialization-serialize-builtin-types.md  | 95 +++++++++++++++----
 1 file changed, 74 insertions(+), 21 deletions(-)

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
index 9b4362bb4..0295060e3 100644
--- a/docs-website/topics/serialization-serialize-builtin-types.md
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -1,12 +1,12 @@
 [//]: # (title: Serialize built-in types)
 
-The Kotlin serialization library supports various built-in types, including basic types such as primitives and strings, composite types, and several standard library classes.
+The Kotlin serialization library supports various built-in types, including basic types such as primitives and strings, as well as certain standard library classes.
 The following sections describe these types in detail and provide examples of how to serialize them.
 
 ## Basic types
 
 Kotlin serialization provides built-in serializers for types that are represented as a single value in serialized data.
-This includes, primitives, strings, and enums.
+This includes primitives, strings, and enums.
 
 For example, here’s how you can serialize a `Long` type:
 
@@ -53,15 +53,39 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-### Long numbers as strings
+### Unsigned numbers
 
-When you serialize Kotlin `Long` values to JSON, JavaScript's native number type can't represent the full range of a Kotlin `Long` type,
-leading to precision loss.
+Kotlin Serialization supports Kotlin's [unsigned integer types](unsigned-integer-types.md) like `UByte` and `UInt`.
+In JSON, these values are serialized as regular JSON numbers and preserve their full unsigned range:
 
-Kotlin/JS handles these large `Long` numbers correctly, but JavaScript's native methods don't.
-A common workaround is to represent long numbers with full precision using the JSON string type.
-Kotlin Serialization supports this approach with [`LongAsStringSerializer`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.builtins/-long-as-string-serializer/).
-To apply it to a `Long` property, use the `@Serializable` annotation:
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+
+//sampleStart
+@Serializable
+class Counter(val counted: UByte, val description: String)
+
+fun main() {
+    val counted = 239.toUByte()
+    println(Json.encodeToString(Counter(counted, "tries")))
+    // {"counted":239,"description":"tries"}
+}
+//sampleEnd
+```
+{kotlin-runnable="true"}
+
+> Unsigned numbers are currently only supported in the JSON format.
+> Other formats such as ProtoBuf and CBOR serialize these types using their signed counterparts internally.
+>
+{style="note"} 
+
+### `Long` numbers as strings
+
+You can represent `Long` numbers as strings in JSON.
+This is useful in JavaScript environments, where JavaScript's `Number` type can't precisely represent all Kotlin `Long` values, which may lead to precision loss.
+
+Use [`LongAsStringSerializer`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.builtins/-long-as-string-serializer/) with the `@Serializable` annotation to encode `Long` values as strings in JSON:
 
 ```kotlin
 import kotlinx.serialization.*
@@ -71,7 +95,7 @@ import kotlinx.serialization.json.*
 //sampleStart
 @Serializable
 class Data(
-    @Serializable(with=LongAsStringSerializer::class)
+    @Serializable(LongAsStringSerializer::class)
     val signature: Long
 )
 
@@ -148,10 +172,10 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-## Composite types
+## Standard library types
 
-Kotlin Serialization supports several composite types from the standard library, but some classes,
-such as ranges and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class aren't supported yet.
+Kotlin Serialization supports several types from the standard library, but some classes,
+such as ranges and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class, aren't supported.
 
 ### Pair and triple
 
@@ -176,8 +200,15 @@ fun main() {
 
 ### Collections
 
-Kotlin Serialization supports collection types such as [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
-Lists and sets are serialized as JSON arrays, and maps are represented as JSON objects.
+Kotlin Serialization supports collection types, including both immutable and mutable variants of [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
+It also supports their concrete implementations such as [`ArrayList`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-array-list/) and [`LinkedHashSet`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-linked-hash-set/), as well as generic and primitive array types.
+The way these collections are represented depends on the serialization format.
+
+In JSON, lists and sets are serialized as JSON arrays, and maps are represented as JSON objects.
+
+Kotlin uses the declared type to deserialize JSON.
+During deserialization, the type of the resulting object is determined by the static type specified in the source code.
+This type can be either the type of the property or the type parameter of the decoding function.
 
 #### Serialize lists
 
@@ -228,6 +259,10 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
+> By default, you can deserialize sets with duplicate entries. The behavior for handling duplicates depends on the specific `Set` implementation.
+> 
+{style="tip"}
+
 #### Serialize maps
 
 Kotlin serialization supports [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/) types with primitive or enum keys:
@@ -262,8 +297,7 @@ In JSON, maps are represented as objects. Since JSON object keys are always stri
 
 #### Deserialization behavior of collections
 
-Kotlin uses the declared type to deserialize JSON.
-For example, a `List` preserves duplicates, while a `Set` enforces uniqueness:
+
 
 ```kotlin
 import kotlinx.serialization.*
@@ -295,7 +329,7 @@ fun main() {
 >
 {style="tip"}
 
-## Unit and singleton objects
+### Unit and singleton objects
 
 The Kotlin [`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/) type and other singleton objects are serializable.
 A [singleton](object-declarations.md) is a class with only one instance, where the state is defined by the object itself rather than by external properties.
@@ -326,9 +360,9 @@ fun main() {
 >
 {style="tip"}
 
-## Duration
+### Duration and Instant
 
-Kotlin's [`Duration`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.time/-duration/) class is serialized to a JSON string using the ISO-8601-2 format:
+Kotlin's [`Duration`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.time/-duration/) type is serialized to a string using the ISO-8601-2 format:
 
 ```kotlin
 import kotlinx.serialization.*
@@ -345,7 +379,26 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-## Nothing
+Similarly, Kotlin's [`Instant`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-instant/) type
+is serialized as a string representing a point in time using the ISO-8601-1 format:
+
+```kotlin
+import kotlinx.serialization.*
+import kotlinx.serialization.json.*
+import kotlin.time.*
+
+//sampleStart
+fun main() {
+    val instant = Instant.fromEpochMilliseconds(1607505416124)
+    println(Json.encodeToString(instant))
+    // "2020-12-09T09:16:56.124Z"
+}
+//sampleEnd
+
+```
+{kotlin-runnable="true" kotlin-min-compiler-version="2.2"}
+
+### Nothing
 
 The [`Nothing`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-nothing.html) type is serializable by default.
 It has no instances, so encoding or decoding it throws an exception.

From 3f475f06b34e98428725ad16378d9ec31f628d03 Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Tue, 21 Oct 2025 15:53:33 +0200
Subject: [PATCH 3/7] update: implementing second review round comments

---
 .../serialization-serialize-builtin-types.md    | 17 +++++++++--------
 docs-website/topics/serialization.md            |  5 +++++
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
index 0295060e3..101dc6ecc 100644
--- a/docs-website/topics/serialization-serialize-builtin-types.md
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -75,8 +75,8 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-> Unsigned numbers are currently only supported in the JSON format.
-> Other formats such as ProtoBuf and CBOR serialize these types using their signed counterparts internally.
+> Although JSON preserves the full range of unsigned numbers, other serialization formats may handle them differently.
+> For example, ProtoBuf and CBOR serialize these types using their signed counterparts.
 >
 {style="note"} 
 
@@ -200,7 +200,7 @@ fun main() {
 
 ### Collections
 
-Kotlin Serialization supports collection types, including both immutable and mutable variants of [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
+Kotlin Serialization supports collection types, including both read-only and mutable variants of [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
 It also supports their concrete implementations such as [`ArrayList`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-array-list/) and [`LinkedHashSet`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-linked-hash-set/), as well as generic and primitive array types.
 The way these collections are represented depends on the serialization format.
 
@@ -259,7 +259,7 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-> By default, you can deserialize sets with duplicate entries. The behavior for handling duplicates depends on the specific `Set` implementation.
+> By default, you can deserialize sets with duplicate entries. The behavior for handling duplicates is implementation-defined.
 > 
 {style="tip"}
 
@@ -288,7 +288,9 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
+Map serialization depends on the format.
 In JSON, maps are represented as objects. Since JSON object keys are always strings, keys are encoded as strings even if they are numbers in Kotlin.
+Other formats, such as CBOR, support maps with non-primitive or object keys and preserve them as such.
 
 > JSON doesn't natively support complex or composite keys.
 > To encode structured objects as map keys, see [Encode structured map keys](serialization-json-configuration.md#encode-structured-map-keys).
@@ -331,7 +333,7 @@ fun main() {
 
 ### Unit and singleton objects
 
-The Kotlin [`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/) type and other singleton objects are serializable.
+Kotlin's [`Unit`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/) type and other singleton objects are serializable.
 A [singleton](object-declarations.md) is a class with only one instance, where the state is defined by the object itself rather than by external properties.
 In JSON, singleton objects are serialized as empty structures:
 
@@ -379,8 +381,8 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-Similarly, Kotlin's [`Instant`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-instant/) type
-is serialized as a string representing a point in time using the ISO-8601-1 format:
+Starting with Kotlin 2.2.0, you can serialize Kotlin's [`Instant`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-instant/) type
+as a string representing a point in time using the ISO-8601-1 format:
 
 ```kotlin
 import kotlinx.serialization.*
@@ -394,7 +396,6 @@ fun main() {
     // "2020-12-09T09:16:56.124Z"
 }
 //sampleEnd
-
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="2.2"}
 
diff --git a/docs-website/topics/serialization.md b/docs-website/topics/serialization.md
index e05bf278a..bc7cf0be1 100644
--- a/docs-website/topics/serialization.md
+++ b/docs-website/topics/serialization.md
@@ -19,6 +19,11 @@ It walks you through adding the Kotlin serialization library to your project and
 Kotlin serialization offers support for all platforms, including JVM, JavaScript, and Native.
 You can use the same [dependency declaration](serialization-get-started.md#add-plugins-and-dependencies-for-kotlin-serialization) regardless of the target platform.
 
+> When you’re not using a specific format library, for example, when you're writing your own serialization format,
+> use the `kotlinx-serialization-core` library as the dependency.
+>
+{style="tip"}
+
 Kotlin serialization supports various serialization formats, such as JSON, CBOR, and Protocol buffers through different serialization format libraries.
 These libraries build on the core `kotlinx.serialization` library.
 For the complete list of supported serialization formats, see [Supported serialization formats](#supported-serialization-formats).

From e8e7b46d5a9a206be75d42d28d2761c48010cd1a Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Wed, 22 Oct 2025 15:41:32 +0200
Subject: [PATCH 4/7] update: moving tip and removing objects

---
 .../topics/serialization-serialize-builtin-types.md    |  2 +-
 docs-website/topics/serialization.md                   | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
index 101dc6ecc..7783edf7d 100644
--- a/docs-website/topics/serialization-serialize-builtin-types.md
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -290,7 +290,7 @@ fun main() {
 
 Map serialization depends on the format.
 In JSON, maps are represented as objects. Since JSON object keys are always strings, keys are encoded as strings even if they are numbers in Kotlin.
-Other formats, such as CBOR, support maps with non-primitive or object keys and preserve them as such.
+Other formats, such as CBOR, support maps with non-primitive keys and preserve them as such.
 
 > JSON doesn't natively support complex or composite keys.
 > To encode structured objects as map keys, see [Encode structured map keys](serialization-json-configuration.md#encode-structured-map-keys).
diff --git a/docs-website/topics/serialization.md b/docs-website/topics/serialization.md
index bc7cf0be1..f2b65657e 100644
--- a/docs-website/topics/serialization.md
+++ b/docs-website/topics/serialization.md
@@ -19,11 +19,6 @@ It walks you through adding the Kotlin serialization library to your project and
 Kotlin serialization offers support for all platforms, including JVM, JavaScript, and Native.
 You can use the same [dependency declaration](serialization-get-started.md#add-plugins-and-dependencies-for-kotlin-serialization) regardless of the target platform.
 
-> When you’re not using a specific format library, for example, when you're writing your own serialization format,
-> use the `kotlinx-serialization-core` library as the dependency.
->
-{style="tip"}
-
 Kotlin serialization supports various serialization formats, such as JSON, CBOR, and Protocol buffers through different serialization format libraries.
 These libraries build on the core `kotlinx.serialization` library.
 For the complete list of supported serialization formats, see [Supported serialization formats](#supported-serialization-formats).
@@ -38,6 +33,11 @@ For example:
 The `kotlinx.serialization` libraries follow their own versioning, independent of Kotlin.
 You can find the latest release versions on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases).
 
+> When you’re not using a specific format library, for example, when you're writing your own serialization format,
+> use the `kotlinx-serialization-core` library as the dependency.
+>
+{style="tip"}
+
 ## Supported serialization formats
 
 `kotlinx.serialization` includes serialization format libraries for various formats:

From dee407bfc17e4096ffa2e168543f6683b6f93788 Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Fri, 24 Oct 2025 11:56:21 +0200
Subject: [PATCH 5/7] fix: capitalization of Kotlin serialization for
 consistency

---
 .../topics/serialization-serialize-builtin-types.md       | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
index 7783edf7d..c3ab8eb45 100644
--- a/docs-website/topics/serialization-serialize-builtin-types.md
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -55,7 +55,7 @@ fun main() {
 
 ### Unsigned numbers
 
-Kotlin Serialization supports Kotlin's [unsigned integer types](unsigned-integer-types.md) like `UByte` and `UInt`.
+Kotlin serialization supports Kotlin's [unsigned integer types](unsigned-integer-types.md) like `UByte` and `UInt`.
 In JSON, these values are serialized as regular JSON numbers and preserve their full unsigned range:
 
 ```kotlin
@@ -174,7 +174,7 @@ fun main() {
 
 ## Standard library types
 
-Kotlin Serialization supports several types from the standard library, but some classes,
+Kotlin serialization supports several types from the standard library, but some classes,
 such as ranges and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class, aren't supported.
 
 ### Pair and triple
@@ -200,7 +200,7 @@ fun main() {
 
 ### Collections
 
-Kotlin Serialization supports collection types, including both read-only and mutable variants of [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
+Kotlin serialization supports collection types, including both read-only and mutable variants of [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/).
 It also supports their concrete implementations such as [`ArrayList`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-array-list/) and [`LinkedHashSet`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-linked-hash-set/), as well as generic and primitive array types.
 The way these collections are represented depends on the serialization format.
 
@@ -212,7 +212,7 @@ This type can be either the type of the property or the type parameter of the de
 
 #### Serialize lists
 
-Kotlin Serialization serializes [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/) types as JSON arrays.
+Kotlin serialization serializes [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/) types as JSON arrays.
 Here’s an example with a list of classes:
 
 ```kotlin

From e4263d179c5f11449560c11688544d089f2e4c1c Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Fri, 7 Nov 2025 16:57:12 +0100
Subject: [PATCH 6/7] update: implementing comments from Sarah for TWr review

---
 .../serialization-serialize-builtin-types.md  | 29 ++++++++++---------
 docs-website/topics/serialization.md          |  2 +-
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
index c3ab8eb45..fc3a4f0c1 100644
--- a/docs-website/topics/serialization-serialize-builtin-types.md
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -1,14 +1,14 @@
 [//]: # (title: Serialize built-in types)
 
-The Kotlin serialization library supports various built-in types, including basic types such as primitives and strings, as well as certain standard library classes.
-The following sections describe these types in detail and provide examples of how to serialize them.
+The Kotlin serialization library supports a variety of built-in types, including basic types such as primitives and strings, as well as certain standard library classes.
+The following sections describe these types in detail and show how to serialize them.
 
 ## Basic types
 
 Kotlin serialization provides built-in serializers for types that are represented as a single value in serialized data.
 This includes primitives, strings, and enums.
 
-For example, here’s how you can serialize a `Long` type:
+For example, here's how you can serialize a `Long` type:
 
 ```kotlin
 // Imports the necessary library declarations
@@ -26,7 +26,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-long-class"}
 
 ### Numbers
 
@@ -138,17 +138,13 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-> On Kotlin/JS and Kotlin/Native, you must use the `@Serializable` annotation for an `enum` class to use as a root object,
+> When targeting Kotlin/JS or Kotlin/Native, you must use the `@Serializable` annotation for an `enum` class to use it as a root object,
 > such as in `encodeToString<Status>(Status.SUPPORTED)`.
 >
 {style="note"}
 
 #### Customize serial names of enum entries
 
-> For more information on customizing serial names, see [Customize serial names](serialization-customization-options.md#customize-serial-names).
->
-{style="tip"}
-
 To customize the serial names of enum entries, use the `@SerialName` annotation and mark the enum class with `@Serializable`:
 
 ```kotlin
@@ -172,6 +168,8 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
+For more information on customizing serial names, see [Customize serial names](serialization-customization-options.md#customize-serial-names).
+
 ## Standard library types
 
 Kotlin serialization supports several types from the standard library, but some classes,
@@ -213,7 +211,7 @@ This type can be either the type of the property or the type parameter of the de
 #### Serialize lists
 
 Kotlin serialization serializes [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/) types as JSON arrays.
-Here’s an example with a list of classes:
+Here's an example with a list of classes:
 
 ```kotlin
 import kotlinx.serialization.*
@@ -259,10 +257,12 @@ fun main() {
 ```
 {kotlin-runnable="true"}
 
-> By default, you can deserialize sets with duplicate entries. The behavior for handling duplicates is implementation-defined.
+> By default, you can deserialize sets with duplicate entries.
 > 
 {style="tip"}
 
+<!-- The behavior for handling duplicates is implementation-defined. -->
+
 #### Serialize maps
 
 Kotlin serialization supports [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/) types with primitive or enum keys:
@@ -299,7 +299,8 @@ Other formats, such as CBOR, support maps with non-primitive keys and preserve t
 
 #### Deserialization behavior of collections
 
-
+Kotlin uses the declared type to deserialize JSON.
+For example, with collections, a `List` preserves duplicates, while a `Set` enforces uniqueness:
 
 ```kotlin
 import kotlinx.serialization.*
@@ -319,7 +320,7 @@ fun main() {
             "b": [42, 42]
         }
     """)
-    // Duplicates are removed from data.b because Set enforces unique elements
+    // Duplicates are removed from data.b because the Set type enforces unique elements
     println(data)
     // Data(a=[42, 42], b=[42])
 }
@@ -427,6 +428,6 @@ fun main() {
 
 ## What's next
 
-* Dive into the [Serialize classes](serialization-customization-options.md) section to learn how to serialize classes and how to modify the default behavior of the `@Serializable` annotation.
+* Dive into [Serialize classes](serialization-customization-options.md) to learn how to serialize classes and how to modify the default behavior of the `@Serializable` annotation.
 * To explore more complex JSON serialization scenarios, see [JSON serialization overview](configure-json-serialization.md).
 * Learn more about polymorphism and serializing different types through a shared base in [Serialize polymorphic classes](serialization-polymorphism.md).
diff --git a/docs-website/topics/serialization.md b/docs-website/topics/serialization.md
index f2b65657e..ea76e1bb9 100644
--- a/docs-website/topics/serialization.md
+++ b/docs-website/topics/serialization.md
@@ -33,7 +33,7 @@ For example:
 The `kotlinx.serialization` libraries follow their own versioning, independent of Kotlin.
 You can find the latest release versions on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases).
 
-> When you’re not using a specific format library, for example, when you're writing your own serialization format,
+> When you're not using a specific format library, for example, when you're writing your own serialization format,
 > use the `kotlinx-serialization-core` library as the dependency.
 >
 {style="tip"}

From de9104bb8b17e0fa1c597f9dab37882450af3948 Mon Sep 17 00:00:00 2001
From: Daniel Csorba <daniel.csorba@jetbrains.com>
Date: Tue, 11 Nov 2025 16:27:22 +0100
Subject: [PATCH 7/7] update: adding ids to the runnable examples

---
 .../serialization-serialize-builtin-types.md  | 28 +++++++++----------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs-website/topics/serialization-serialize-builtin-types.md b/docs-website/topics/serialization-serialize-builtin-types.md
index fc3a4f0c1..feed03dd4 100644
--- a/docs-website/topics/serialization-serialize-builtin-types.md
+++ b/docs-website/topics/serialization-serialize-builtin-types.md
@@ -51,7 +51,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-numbers"}
 
 ### Unsigned numbers
 
@@ -73,7 +73,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-unsigned-numbers"}
 
 > Although JSON preserves the full range of unsigned numbers, other serialization formats may handle them differently.
 > For example, ProtoBuf and CBOR serialize these types using their signed counterparts.
@@ -106,7 +106,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-long-as-string"}
 
 > You can also specify serializers like `LongAsStringSerializer` for all properties in a file.
 > For more information, see [Specify serializers for a file](third-party-classes.md#specify-serializers-for-a-file).
@@ -136,7 +136,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-enum"}
 
 > When targeting Kotlin/JS or Kotlin/Native, you must use the `@Serializable` annotation for an `enum` class to use it as a root object,
 > such as in `encodeToString<Status>(Status.SUPPORTED)`.
@@ -166,7 +166,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-enum-serialname"}
 
 For more information on customizing serial names, see [Customize serial names](serialization-customization-options.md#customize-serial-names).
 
@@ -194,7 +194,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-pair"}
 
 ### Collections
 
@@ -231,7 +231,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-list"}
 
 #### Serialize sets
 
@@ -255,7 +255,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-set"}
 
 > By default, you can deserialize sets with duplicate entries.
 > 
@@ -286,7 +286,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-map"}
 
 Map serialization depends on the format.
 In JSON, maps are represented as objects. Since JSON object keys are always strings, keys are encoded as strings even if they are numbers in Kotlin.
@@ -326,7 +326,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-collections"}
 
 > For more information about collections in Kotlin, see [Collections overview](collections-overview.md).
 >
@@ -356,7 +356,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-singleton"}
 
 > You can use serialized singleton objects in [closed polymorphic hierarchies](serialization-polymorphism.md#serialize-objects-in-sealed-hierarchies)
 > to represent cases without additional fields.
@@ -380,7 +380,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-duration"}
 
 Starting with Kotlin 2.2.0, you can serialize Kotlin's [`Instant`](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.time/-instant/) type
 as a string representing a point in time using the ISO-8601-1 format:
@@ -398,7 +398,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true" kotlin-min-compiler-version="2.2"}
+{kotlin-runnable="true" kotlin-min-compiler-version="2.2" id="serialize-instant"}
 
 ### Nothing
 
@@ -424,7 +424,7 @@ fun main() {
 }
 //sampleEnd
 ```
-{kotlin-runnable="true"}
+{kotlin-runnable="true" id="serialize-nothing"}
 
 ## What's next