Skip to content

Clarify that it is preferable to have unique class' serial name #3098

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sandwwraith merged 2 commits into from
Oct 29, 2025
+13 −2
Merged

Clarify that it is preferable to have unique class' serial name #3098

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64db2f9
Clarify that it is preferable to have unique class' serial name
sandwwraith Oct 23, 2025
9e3be2d
fixup! Clarify that it is preferable to have unique class' serial name
sandwwraith Oct 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion core/commonMain/src/kotlinx/serialization/Annotations.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,10 @@ public annotation class Serializer(
* println(Json.encodeToString(CustomName(42)))
* ```
*
* If a name of class or property is overridden with this annotation, original source code name is not available for the library.
* When picking a serial name for a class, avoid assigning the same name to different classes.
* Check out Equality rules for [SerialDescriptor] to make sure that class descriptor will stay unique.
*
* If a name of a class or property is overridden with this annotation, the original source code name is not available for the library.
* Tools like `JsonNamingStrategy` and `ProtoBufSchemaGenerator` would see and transform [value] from [SerialName] annotation.
*/
@MustBeDocumented
Expand Down
8 changes: 7 additions & 1 deletion docs/polymorphism.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -234,6 +234,9 @@ This way we can have a stable _serial name_ that is not affected by the class's
> In addition to that, JSON can be configured to use a different key name for the class discriminator.
> You can find an example in the [Class discriminator for polymorphism](json.md#class-discriminator-for-polymorphism) section.

When picking a serial name for a class, avoid assigning the same name to different classes.
Check out equality rules in documentation for [SerialDescriptor] to make sure that class descriptor will stay unique.

### Concrete properties in a base class

A base class in a sealed hierarchy can have properties with backing fields.
Expand Down Expand Up @@ -1017,6 +1020,10 @@ The next chapter covers [JSON features](json.md).
[DeserializationStrategy]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-deserialization-strategy/index.html
[SerializationStrategy]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization/-serialization-strategy/index.html

<!--- INDEX kotlinx-serialization-core/kotlinx.serialization.descriptors -->

[SerialDescriptor]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.descriptors/-serial-descriptor/index.html

<!--- INDEX kotlinx-serialization-core/kotlinx.serialization.modules -->

[SerializersModule]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module/index.html
Expand All @@ -1037,4 +1044,3 @@ The next chapter covers [JSON features](json.md).
[Json]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/index.html

<!--- END -->