feat: adding the Serialize classes page #3097

daniCsorbaJB · 2025-10-23T15:35:40Z

This is the fourth part of the Kotlin Serialization rewrite task.

Related YouTract ticket is here: KT-81889 [Docs] Create a Serialize classes page for kotlinx.serialization

sandwwraith

.

daniCsorbaJB · 2025-10-31T09:33:26Z

docs-website/topics/serialization-customization-options.md

@@ -0,0 +1,505 @@
+[//]: # (title: Serialize classes)
+
+The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation in Kotlin enables the serialization of all properties in classes defined by the primary constructor.


nice, good point - changed it to properties with backing fields here as well 👍

docs-website/topics/serialization-customization-options.md

daniCsorbaJB · 2025-10-31T09:33:26Z

docs-website/topics/serialization-customization-options.md

@@ -0,0 +1,505 @@
+[//]: # (title: Serialize classes)
+
+The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation in Kotlin enables the serialization of all properties in classes defined by the primary constructor.


nice, good point - changed it to properties with backing fields here as well 👍

docs-website/topics/serialization-customization-options.md

sandwwraith

I do not know whether we'll finish whole review before mid-December (I expect next release of serialization there), but we can leave opt-in note for now and delete it later.

Besides that, please fix "Defines..." wording and my other comment and we're good to go

docs-website/topics/serialization-customization-options.md

sarahhaggarty

Looks great! I have some suggestions for you to consider and a couple clarification questions :)

docs-website/topics/serialization-customization-options.md

sarahhaggarty · 2025-11-18T15:54:51Z

docs-website/topics/serialization-customization-options.md

@@ -0,0 +1,516 @@
+[//]: # (title: Serialize classes)
+
+The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields.


Suggested change

The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields.

By default, the [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation serializes all class properties that have backing fields.

What do you think of this version?

I'm not sure it is good to imply that the annotation serializes. While it is "simpler" it is also misleading, potentially leading to misunderstandings. What about stating it indirectly:
"By default, the @Serializable annotation causes all class properties that have backing fields to be serialized."

I also think I prefer the original phrasing here — it captures what happens a bit better (as @pdvrieze says, it doesn't perform serialization on its own - it essentially generates the default serializer under the hood, which enables the serialization of class properties with backing fields )

sarahhaggarty · 2025-11-18T15:56:03Z

docs-website/topics/serialization-customization-options.md

+
+The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields.
+You can further customize this behavior to fit your specific needs.
+This page covers various serialization techniques, showing you how to specify which properties are serialized and how the serialization process is managed.


Suggested change

This page covers various serialization techniques, showing you how to specify which properties are serialized and how the serialization process is managed.

This page covers various serialization techniques, showing you how to specify which properties are serialized, and how the serialization process is managed.

Is the process managed by the library?

The overall process starts with the format (which could be Json or another library provided format), and then parts of it are determined by the actual serializers (either plugin generated or custom). The core library does not actually do much in terms of the process (except define a way in which it should happen). In other words, there is no serialization "loop" that formats plug in to, but rather the format manages/controls the process as restricted/defined by the core library.

and how the serialization process is managed

I think what implied here is that library manages the process, and you can manage it by using different things from library, such as @Transient annotation

sarahhaggarty · 2025-11-18T15:59:19Z

docs-website/topics/serialization-customization-options.md

+```
+{kotlin-runnable="true" id="serialize-annotation-example"}
+
+### Serialization of class references


What do you think about "Serialize class references" as a header? So that the header style matches the others on the page?

This header (and the ones below) provide specifics as to how specific kinds of elements (attributes) are handled, but this is not an active user thing. As such the verb "serialize" is misleading.

sarahhaggarty · 2025-11-18T15:59:33Z

docs-website/topics/serialization-customization-options.md

+>
+{style="tip"}
+
+### Serialization of repeated object references


What do you think about "Serialize repeated object references" as a header? So that the header style matches the others on the page?

sarahhaggarty · 2025-11-18T16:51:04Z

docs-website/topics/serialization-customization-options.md

+
+## Customize class serialization
+
+Kotlin Serialization provides several ways to modify how classes are serialized.


What do you think about "control" instead of "modify"?

As the section leaves out custom serializers (as a reference to more details for this "advanced" option), it is more a matter of adjustment/modification (I would prefer adjustment, but it might be a bit of a "hard" word).

I also prefer modify here slightly (also this way we can avoid repeating control from the following sentence)

sarahhaggarty · 2025-11-18T16:53:43Z

docs-website/topics/serialization-customization-options.md

+
+You can customize these names, called _serial names_,
+with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation.
+Use it to make a property name more descriptive in the serialized output:


Here you say that you should use it to make the property more descriptive. But in the example you abbreviate it. So maybe we should change the wording or the example?

And in reality the key function is compatibility with other serialization systems/existing formats. I think the wording needs to be adjusted. Maybe too advanced would be that it may also be used to ensure a property's serialized name is stable under refactoring/renaming of the underlying kotlin property.

I made the example match this (ensured that it's it the other way around to be more descriptive)

docs-website/topics/serialization-customization-options.md

sarahhaggarty · 2025-11-18T17:00:31Z

docs-website/topics/serialization-customization-options.md

+
+### Validate data in the primary constructor
+
+After deserialization, the `kotlinx.serialization` plugin runs the class's initializer blocks,


Could you add a link here to the Kotlin section about initializer blocks? https://kotlinlang.org/docs/classes.html#initializer-blocks

good idea 💯

sarahhaggarty · 2025-11-18T17:02:09Z

docs-website/topics/serialization-customization-options.md

+You can exclude a property from serialization with the [`@Transient`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-transient/) annotation.
+Transient properties must have a default value.
+
+If you explicitly specify a value for a transient property in the input, even if it matches the default value, a `JsonDecodingException` is thrown:


Again, I'm not sure what "input" is referring to exactly here 🤔

The input here is the Json formatted data that is being deserialized (converted into Kotlin datastructures). What is actually going on here is that the serializer does not record transient properties in its descriptor, so when it encounters the property name it is treated as any other unknown attribute, which by default is to throw an exception (there is an option to ignore unknown fields).

feat: adding the Serialize classes page

8f0d35a

daniCsorbaJB requested a review from sandwwraith October 23, 2025 15:36

sandwwraith requested changes Oct 28, 2025

View reviewed changes

daniCsorbaJB commented Oct 31, 2025

View reviewed changes

docs-website/topics/serialization-customization-options.md Outdated Show resolved Hide resolved

update: implementing review comments

372e4c9

sandwwraith requested changes Nov 3, 2025

View reviewed changes

update: implementing additional review comments

3905df9

sandwwraith reviewed Nov 4, 2025

View reviewed changes

docs-website/topics/serialization-customization-options.md Show resolved Hide resolved

update: small code clean up and adding experimental API information

bfee2a3

sandwwraith requested changes Nov 5, 2025

View reviewed changes

docs-website/topics/serialization-customization-options.md Outdated Show resolved Hide resolved

daniCsorbaJB added 2 commits November 6, 2025 09:27

update: removing experimental and adding some finishing touches

638032e

update: adding runnable example ids

9a71cef

sandwwraith approved these changes Nov 12, 2025

View reviewed changes

daniCsorbaJB assigned sarahhaggarty Nov 13, 2025

sarahhaggarty requested changes Nov 18, 2025

View reviewed changes

update: implementing technical writer review comments

85493b3

		@@ -0,0 +1,505 @@
		[//]: # (title: Serialize classes)

		The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation in Kotlin enables the serialization of all properties in classes defined by the primary constructor.

		@@ -0,0 +1,516 @@
		[//]: # (title: Serialize classes)

		The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields.

	The [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation enables the default serialization of all class properties with backing fields.
	By default, the [`@Serializable`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serializable/) annotation serializes all class properties that have backing fields.

	This page covers various serialization techniques, showing you how to specify which properties are serialized and how the serialization process is managed.
	This page covers various serialization techniques, showing you how to specify which properties are serialized, and how the serialization process is managed.


		## Customize class serialization

		Kotlin Serialization provides several ways to modify how classes are serialized.


		### Validate data in the primary constructor

		After deserialization, the `kotlinx.serialization` plugin runs the class's initializer blocks,

feat: adding the Serialize classes page #3097

Are you sure you want to change the base?

feat: adding the Serialize classes page #3097

Uh oh!

Conversation

daniCsorbaJB commented Oct 23, 2025

Uh oh!

sandwwraith left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sandwwraith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarahhaggarty left a comment

Choose a reason for hiding this comment

Uh oh!

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!

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!

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!

Reviewers

Assignees

Labels

Projects