feat: adding new page for polymorphism by daniCsorbaJB · Pull Request #3141 · Kotlin/kotlinx.serialization

daniCsorbaJB · 2026-01-16T10:20:20Z

This PR adds the page related to Polymorphism to the rewritten Kotlin serialization docs

Related Youtrack ticket: KT-83541

sandwwraith

.

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

docs-website/topics/serialization-polymorphism.md

sandwwraith

Overall structure looks good

sandwwraith · 2026-02-17T16:48:13Z

docs-website/topics/serialization-polymorphism.md

+Polymorphism allows objects of different types to be serialized through a common declared supertype.
+This applies to class polymorphism, where subclasses share a common interface or base class.
+
+> This section focuses on class polymorphism, where subclasses share a common interface or base class.


This line duplicates the one above. I think you can remove the tip completely and join the references:

Class polymorphism allows working with objects of different types via common interface or a base class. Kotlin serialization supports polymorphism, allowing different types to be serialized through a common declared supertype. For an overview of how interfaces and inheritance work in Kotlin, see [Interfaces](interfaces.md) and [Inheritance](inheritance.md). Kotlin serialization is static by default. ...

Sounds good, I like it 👍

sandwwraith · 2026-02-17T16:50:41Z

docs-website/topics/serialization-polymorphism.md

+
+In this example, even though the runtime value is the `OwnedProject` subclass, only the properties of the declared `Project` static type are serialized.
+
+Kotlin serialization supports two ways to work with polymorphic hierarchies:


I think we need some kind of joiner to the previous sentence here. WDYT of "To serialize runtime values, you need to use one of two ways to work with polymorphic hierarchies:"?

I see what you mean 🤔
I think it's a good idea to connect it with an active sentence.

Regarding the "runtime" part do you think that's necessary? 🤔 WDYT:

To serialize values in a polymorphic class hierarchy, Kotlin serialization provides two approaches:

sandwwraith · 2026-02-17T16:51:34Z

docs-website/topics/serialization-polymorphism.md

+
+A class hierarchy is considered to use closed polymorphism when all possible subclasses are guaranteed to be known at compile time.
+
+To provide this guarantee, [use a `sealed class` or `interface` as the base type](#serialize-closed-polymorphic-classes).


Giving a link to literally the next line feels pointless. Maybe you wanted to link to https://kotlinlang.org/docs/sealed-classes.html instead?

Also: "sealed class or sealed interface" for more emphasis.

agreed to both 👍

It may be worthwhile to especially highlight sealed interfaces as being able to support module-free/closed polymorphism without restricting the class hierarchy.

sandwwraith · 2026-02-17T16:55:42Z

docs-website/topics/serialization-polymorphism.md

+
+To provide this guarantee, [use a `sealed class` or `interface` as the base type](#serialize-closed-polymorphic-classes).
+
+### Serialize closed polymorphic classes


This is the only section under "Closed polymorphism in Kotlin serialization" — are you sure sub-header is needed?

🤔 I added it mainly for Table of Contents scannability + better metadata (what people will see when they hover over open/closed polymorphism if we link to it - tbh this we can still retain with your proposal so not much of an issue).

On the other hand, If we remove the “Closed polymorphism” and “Open polymorphism” parent sections and move “Serialize closed…” and “Serialize open…” to the second level, we introduce four additional entries in the ToC. That pushes the current fourth-level sections higher and makes the ToC longer.

On the most common screen resolution that would require scrolling to see all entries. (but tbh it might not be as important so we might not be able to avoid this anyway 😞 )

I'll test how it looks that way 👍 — also as an alternative, we could even break the doc into multiple pages.
(Polymorphism overview - Closed polymorphism - Open polymorphism)

sandwwraith · 2026-02-17T16:58:08Z

docs-website/topics/serialization-polymorphism.md

+
+### Serialize closed polymorphic classes
+
+To serialize a closed polymorphic hierarchy, use a `sealed class` or a `sealed interface` as the base type and mark all subclasses with `@Serializable`:


If you remove sub-header, this can be nicely joined:

To provide this guarantee, [use a `sealed class` or `interface` as the base type](#serialize-closed-polymorphic-classes). After you've done that, mark all subclasses with `@Serializable` and you're ready to serialize a closed polymorphic hierarchy:

Is it not also required to mark the base type as @Serializable

sandwwraith · 2026-02-17T18:23:55Z

docs-website/topics/serialization-polymorphism.md

+Interfaces and abstract classes use polymorphic serialization by default.
+
+To serialize a property with a non-serializable type, such as `Any`,
+or when the property’s base type is an open class, annotate the property with [`@Polymorphic`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-polymorphic/).


Suggested change

or when the property’s base type is an open class, annotate the property with [`@Polymorphic`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-polymorphic/).

or when the property’s type is an open class, annotate the property with [`@Polymorphic`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-polymorphic/).

Properties types are fully static.

Also this annotation works on closed types too. It forces the use of the polymorphic serializer (and polymorphic resolution).

sandwwraith · 2026-02-17T18:28:02Z

docs-website/topics/serialization-polymorphism.md

+abstract class Response<out T>
+
+@Serializable
+@SerialName("OkResponse")


Why do we need serial name in this and all examples below?

The examples tend to be a bit much here. It would be possible if only the relevant sections were highlighted and the full code available on user action.

Why do we need serial name in this and all examples below?

I agree we don't need it — removed it. 👍

The examples tend to be a bit much here. It would be possible if only the relevant sections were highlighted and the full code available on user action.

🤔 We could show just the most relevant part, but I'm worried people would get confused what they are merging:

val format = Json { serializersModule = projectModule + responseModule }

sandwwraith · 2026-02-17T18:30:43Z

docs-website/topics/serialization-polymorphism.md

+data class OwnedProject(override val name: String, val owner: String) : Project()
+```
+
+To handle unknown polymorphic subtypes like `BasicProject`, configure a default deserializer for the base type.


BasicProject is not unknown. It is a default choice for other types.

To handle unknown polymorphic subtypes of Project...

sandwwraith · 2026-02-17T18:39:29Z

docs-website/topics/serialization-polymorphism.md

+2. Specify a lambda in `polymorphicDefaultSerializer()` that returns a [`SerializationStrategy`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serialization-strategy/)` for the runtime value.
+
+Let's look at an example with two private classes, `CatImpl` and `DogImpl`.
+To avoid raising their visibility, register a default serializer for `Animal` that selects a serializer based on the runtime value:


"runtime value" would be of a private class in this case. So more correct wording is "selects a serializer based on the public interface:" or "selects a serializer without having to refer to the private implementation classes:"

good point & yes, I agree it shouldn't be runtime value, but doesn't it select it based on runtime type just through the public interface or am I wrong here? 🤔

so perhaps would it work with:

...that selects a serializer based on the runtime type through public interfaces.

sandwwraith · 2026-02-17T18:43:56Z

docs-website/topics/serialization-polymorphism.md

+val module = SerializersModule {
+    polymorphicDefaultSerializer(Animal::class) { instance ->
+        @Suppress("UNCHECKED_CAST")
+        // Determines the appropriate serializer using a when block based on the runtime value


pdvrieze

I had a look through the document. Compared to the previous ones this document gets quite deep into technical complexities.

Even the structure is a bit complex and can probably be streamlined a bit by being very diligent in overlapping/distinct cases as well as (even stronger) separation of aspects (e.g. writing the serializable types vs consumption + SerializerModules).

pdvrieze · 2026-02-27T13:28:37Z

docs-website/topics/serialization-polymorphism.md

+
+A class hierarchy is considered to use closed polymorphism when all possible subclasses are guaranteed to be known at compile time.
+
+To provide this guarantee, [use a `sealed class` or `interface` as the base type](#serialize-closed-polymorphic-classes).


It may be worthwhile to especially highlight sealed interfaces as being able to support module-free/closed polymorphism without restricting the class hierarchy.

pdvrieze · 2026-02-27T13:29:09Z

docs-website/topics/serialization-polymorphism.md

+
+### Serialize closed polymorphic classes
+
+To serialize a closed polymorphic hierarchy, use a `sealed class` or a `sealed interface` as the base type and mark all subclasses with `@Serializable`:


Is it not also required to mark the base type as @Serializable

pdvrieze · 2026-02-27T13:32:50Z

docs-website/topics/serialization-polymorphism.md

+
+By default, Kotlin serialization uses the fully qualified class name as the type discriminator property value for polymorphic subclasses.
+
+You can [customize their serial names](serialization-customization-options.md#customize-serial-names) with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation.


You may also want to be very clear on the distinction between @SerialName applied to the type (in which it specifies the type name for polymorphism - or other format specific purposes), and applied to properties where it specifies the property/element name (not the name of its type).

(in retrospect it would have been good to have a @SerialTypeName annotation as and restrict the annotation targets accordingly)

pdvrieze · 2026-02-27T13:35:21Z

docs-website/topics/serialization-polymorphism.md

+
+You can [customize their serial names](serialization-customization-options.md#customize-serial-names) with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation.
+
+> You must use a unique `@SerialName` for each serializable class in a polymorphic hierarchy. Otherwise, an `IllegalStateException` is thrown.


Also, type names are expected to be unique for the entire use of a format (not just individual invocations) as formats would use this for caching.

The way it is written here implies that it is fine to have conflicting names outside of polymorphism (and it generally isn't – it creates really tricky bugs)

pdvrieze · 2026-02-27T13:38:58Z

docs-website/topics/serialization-polymorphism.md

+> You can also configure JSON to use a different key name for the class discriminator.
+> For more information, see the [Specify class discriminator for polymorphism](serialization-json-configuration.md#specify-class-discriminator-for-polymorphism) section.
+>
+{style="tip"}


For some additional clarity, you may want to mention that "type" is the default name. However, would this tip not be better placed at line 87 (where you actually discuss the "type" attribute).

both good points I agree — moved it and rewrote that part to reflect this 👍

pdvrieze · 2026-02-27T14:15:30Z

docs-website/topics/serialization-polymorphism.md

+Interfaces and abstract classes use polymorphic serialization by default.
+
+To serialize a property with a non-serializable type, such as `Any`,
+or when the property’s base type is an open class, annotate the property with [`@Polymorphic`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-polymorphic/).


Also this annotation works on closed types too. It forces the use of the polymorphic serializer (and polymorphic resolution).

pdvrieze · 2026-02-27T14:25:58Z

docs-website/topics/serialization-polymorphism.md

+Kotlin serialization can't automatically determine the concrete type of a generic type parameter at runtime.
+As a result, it can't pick a serializer for that parameter without explicit configuration.
+
+To provide this configuration, register the subtype in a `SerializersModule` with an explicit serializer.
+`PolymorphicSerializer(Any::class)` has the broadest scope, but you can use a more specific serializer when you know which concrete types the generic value can have.


This is getting quite advanced. It needs a bit more clarity on what it can and can not do. Make clear that this is not needed for the non-polymorphic case or if the generic argument is present on the ancestor:

@Serializable sealed interface Optional<T> { @Serializable object None: Optional<Nothing> @Serializable class Value<T>(val value: T): Optional<T> }

pdvrieze · 2026-02-27T14:27:22Z

docs-website/topics/serialization-polymorphism.md

+abstract class Response<out T>
+
+@Serializable
+@SerialName("OkResponse")


The examples tend to be a bit much here. It would be possible if only the relevant sections were highlighted and the full code available on user action.

pdvrieze · 2026-02-27T14:30:33Z

docs-website/topics/serialization-polymorphism.md

+
+In this example, deserialization doesn't rely on the `type` field to differentiate subtypes and instead uses the plugin-generated serializer for `BasicProject`.
+This approach assumes that unknown subtypes follow a known structure.
+If unknown input varies in structure, use a [custom serializer](create-custom-serializers.md) instead.


Also mention that an alternative is for the format to be configured to ignore unknown keys.

And in most cases this only really works with format specific handling in the custom serializers.

pdvrieze · 2026-02-27T14:36:06Z

docs-website/topics/serialization-polymorphism.md

+You can serialize values of a polymorphic base type without registering every concrete subtype.
+Use this when you don't have access to the full type hierarchy, or when it changes a lot.


Maybe it is worth mentioning that a custom serializer could also be used, and would be nicer from a consumer perspective and more powerful from the provider perspective.

The primary use case for the default seems to be to support forward compatibility.

feat: adding new page for polymorphism

6dcebc4

daniCsorbaJB requested a review from sandwwraith January 19, 2026 13:43

sandwwraith requested changes Jan 27, 2026

View reviewed changes

daniCsorbaJB added 3 commits February 2, 2026 19:35

update: implementing review comments

ee390ee

fix: backticks

b71dfee

update: small update for one example to break it down a little

bab4b5b

sandwwraith requested changes Feb 17, 2026

View reviewed changes

pdvrieze reviewed Feb 27, 2026

View reviewed changes

daniCsorbaJB added 2 commits March 2, 2026 17:11

update: implementing review comments

4b47b4c

fix: small addition of interfaces

072e569


		In this example, even though the runtime value is the `OwnedProject` subclass, only the properties of the declared `Project` static type are serialized.

		Kotlin serialization supports two ways to work with polymorphic hierarchies:


		A class hierarchy is considered to use closed polymorphism when all possible subclasses are guaranteed to be known at compile time.

		To provide this guarantee, [use a `sealed class` or `interface` as the base type](#serialize-closed-polymorphic-classes).


		To provide this guarantee, [use a `sealed class` or `interface` as the base type](#serialize-closed-polymorphic-classes).

		### Serialize closed polymorphic classes


		### Serialize closed polymorphic classes

		To serialize a closed polymorphic hierarchy, use a `sealed class` or a `sealed interface` as the base type and mark all subclasses with `@Serializable`:

	or when the property’s base type is an open class, annotate the property with [`@Polymorphic`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-polymorphic/).
	or when the property’s type is an open class, annotate the property with [`@Polymorphic`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-polymorphic/).


		By default, Kotlin serialization uses the fully qualified class name as the type discriminator property value for polymorphic subclasses.

		You can [customize their serial names](serialization-customization-options.md#customize-serial-names) with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation.


		You can [customize their serial names](serialization-customization-options.md#customize-serial-names) with the [`@SerialName`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serial-name/) annotation.

		> You must use a unique `@SerialName` for each serializable class in a polymorphic hierarchy. Otherwise, an `IllegalStateException` is thrown.

		You can serialize values of a polymorphic base type without registering every concrete subtype.
		Use this when you don't have access to the full type hierarchy, or when it changes a lot.

Conversation

daniCsorbaJB commented Jan 16, 2026

Uh oh!

sandwwraith left a comment

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!

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!

daniCsorbaJB Feb 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

daniCsorbaJB Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

daniCsorbaJB Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

daniCsorbaJB Feb 27, 2026 •

edited

Loading

daniCsorbaJB Mar 2, 2026 •

edited

Loading

daniCsorbaJB Mar 2, 2026 •

edited

Loading