diff --git a/core/commonMain/src/kotlinx/serialization/Annotations.kt b/core/commonMain/src/kotlinx/serialization/Annotations.kt index 183602f20..9d49c351e 100644 --- a/core/commonMain/src/kotlinx/serialization/Annotations.kt +++ b/core/commonMain/src/kotlinx/serialization/Annotations.kt @@ -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 diff --git a/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt b/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt index 67d872f2c..68fba08f0 100644 --- a/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt +++ b/core/commonMain/src/kotlinx/serialization/descriptors/SerialDescriptors.kt @@ -93,6 +93,7 @@ public fun PrimitiveSerialDescriptor(serialName: String, kind: PrimitiveKind): S /** * Factory to create a new descriptor that is identical to [original] except that the name is equal to [serialName]. * Usually used when you want to serialize a type as another type, delegating implementation of `serialize` and `deserialize`. + * Do not use [serialName] that is equal to the name of [original] or other serializable classes. * * Example: * ``` diff --git a/docs/polymorphism.md b/docs/polymorphism.md index 67f0560a0..9294b67c2 100644 --- a/docs/polymorphism.md +++ b/docs/polymorphism.md @@ -234,6 +234,10 @@ 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. +> [!IMPORTANT] +> 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 the class descriptor will stay unique. + ### Concrete properties in a base class A base class in a sealed hierarchy can have properties with backing fields. @@ -1017,6 +1021,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 + + +[SerialDescriptor]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.descriptors/-serial-descriptor/index.html + [SerializersModule]: https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-core/kotlinx.serialization.modules/-serializers-module/index.html @@ -1037,4 +1045,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 -