Doc rewrite update 3 - Serialize built in types #3082

daniCsorbaJB · 2025-09-18T13:10:16Z

This is the third part of the Kotlin Serialization rewrite.

Related YouTract ticket is: KT-80887 [Docs] Create a serialize built-in classes guide for kotlinx.serialization

pdvrieze

I've added some comments. One thing to be clear about is the distinction between json and serialization in general. Json as example is good, but I would avoid giving the impression that serialization is json-only.

pdvrieze · 2025-09-18T14:54:33Z

docs-website/topics/serialization-serialize-builtin-types.md

+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.


Is it worthwhile to note that this is a limitation of JS, not Json that is effectively arbitrary precision? It is somewhat implied by the explanation below, but can be confusing in the distinction.

pdvrieze · 2025-09-18T15:02:32Z

docs-website/topics/serialization-serialize-builtin-types.md

+### 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.


Maybe explicitly mention that this is specific to the Json format. What about:
The way lists and sets are serialized is format specific, but generally mapped to common structures. For example, in Json lists and sets are serialized as ...

pdvrieze · 2025-09-18T15:03:56Z

docs-website/topics/serialization-serialize-builtin-types.md

+> 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"}


Maybe mention that other formats may support this in different ways.

pdvrieze · 2025-09-19T09:08:44Z

docs-website/topics/serialization-serialize-builtin-types.md

+
+## 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:


IIRC, this is not json specific.

Yes, maybe just say "string" instead of "JSON string"?

sandwwraith

see comments

sandwwraith · 2025-09-29T14:44:26Z

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.


You've mentioned 'composite types' without explaining what they are. I suggest just leaving 'basic types such as primitives and strings, as well as certain standard library classes'

sandwwraith · 2025-09-29T15:01:35Z

docs-website/topics/serialization-serialize-builtin-types.md

+## 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.


Unnecessary , after 'includes' ?

sandwwraith · 2025-09-29T15:03:07Z

docs-website/topics/serialization-serialize-builtin-types.md

+//sampleStart
+@Serializable
+class Data(
+    @Serializable(with=LongAsStringSerializer::class)


I'd prefer removing explicit with: @Serializable(LongAsStringSerializer::class)

sandwwraith · 2025-09-29T15:50:11Z

docs-website/topics/serialization-serialize-builtin-types.md

+> For more information, see [Specify serializers for a file](third-party-classes.md#specify-serializers-for-a-file).
+>
+{style="tip"}
+


I think it might worth it to add section aboun unsigned numbers here as well, given they're stable in stdlib and IR compiler has been default for years (https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/value-classes.md#unsigned-types-support-json-only). Just don't forget mentioning

Unsigned types are output as unsigned only in JSON format. Other formats such as ProtoBuf and CBOR use built-in serializers that use an underlying signed representation for unsigned types.

Stating that unsigned is only unsigned in Json is inaccurate, other formats support unsigned directly (and at full range) - maybe something that the protobuf serializer can be extended to do.

sandwwraith · 2025-09-29T16:01:13Z

docs-website/topics/serialization-serialize-builtin-types.md

+```
+{kotlin-runnable="true"}
+
+## Composite types


I would say we don't need this 'composite types' notion until maybe the chapter about custom serializers. So you can replace this with 'Standard library types'

Alternatively, you should start with the definition of composite types: "Every type which is composed out of the basic types dicussed above, is called composite".
Besides, one can always write a serializer that represents any complex type as string. So I'm in favor of removing 'composite types' notion for now.

sandwwraith · 2025-09-29T16:06:38Z

docs-website/topics/serialization-serialize-builtin-types.md

+
+### 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/).


I would rephrase this slightly. The thing is, we also support concrete implementations (e.g. ArrayList and LinkedHashSet), so our users should not have impression that only basic intrefaces are supported. Mutable counterparts should be mentioned as well.

And btw, regular Arrays and primitive Int/Long/...Array too.

sandwwraith · 2025-09-29T16:08:31Z

docs-website/topics/serialization-serialize-builtin-types.md

+    // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}]
+}
+//sampleEnd
+```


Since Sets have their own section, maybe it is worth mentioning that

Duplicate entries in Sets do not cause exceptions on deserialization by default and behavior on duplicates is implementation-defined.

sandwwraith · 2025-09-29T16:10:12Z

docs-website/topics/serialization-serialize-builtin-types.md

+
+#### Deserialization behavior of collections
+
+Kotlin uses the declared type to deserialize JSON.


I think original

During deserialization, the type of the resulting object is determined by the static type that was specified in the source code—either as the type of the property or as the type parameter of the decoding function.

explains what happens better. It also answers the question "What happens if I specify ArrayList or LinkedList"

Although you can mention this in the beginning of the section, add the suggested tip to the Set section and drop this section completely.

sandwwraith · 2025-09-29T16:12:28Z

docs-website/topics/serialization-serialize-builtin-types.md

+
+## 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:


Yes, maybe just say "string" instead of "JSON string"?

sandwwraith · 2025-09-29T16:13:22Z

docs-website/topics/serialization-serialize-builtin-types.md

+>
+{style="tip"}
+
+## Duration


We also have two new serializers for Instant btw (#2945). They probably should be mentioned here (and requirement for Kotlin 2.2)

feat: adding the serialize built in types page

56ec279

daniCsorbaJB requested a review from sandwwraith September 18, 2025 13:10

pdvrieze reviewed Sep 19, 2025

View reviewed changes

sandwwraith requested changes Sep 29, 2025

View reviewed changes

		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.


		## 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:

		@@ -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.


		### 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/).


		#### Deserialization behavior of collections

		Kotlin uses the declared type to deserialize JSON.

Doc rewrite update 3 - Serialize built in types #3082

Are you sure you want to change the base?

Doc rewrite update 3 - Serialize built in types #3082

Uh oh!

Conversation

daniCsorbaJB commented Sep 18, 2025

Uh oh!

pdvrieze left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sandwwraith left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!