Add @JsonNames annotation

via DescriptorSchemaCache internal mechanism
with guide, docs, and samples.

Stabilize .toString() for SerialClassDescImpl; because HashMaps on different platforms have different iteration order.

Disable primary collision detection for optimization purposes.

Add benchmarks on skipping unknown fields.

benchmark/src/jmh/kotlin/kotlinx/benchmarks/json/TwitterFeedBenchmark.kt

@@ -24,6 +24,9 @@ open class TwitterFeedBenchmark {
      */
     private val input = TwitterFeedBenchmark::class.java.getResource("/twitter_macro.json").readBytes().decodeToString()
     private val twitter = Json.decodeFromString(MacroTwitterFeed.serializer(), input)
+    private val jsonNoAltNames = Json { useAlternativeNames = false }
+    private val jsonIgnoreUnknwn = Json { ignoreUnknownKeys = true }
+    private val jsonIgnoreUnknwnNoAltNames = Json { ignoreUnknownKeys = true; useAlternativeNames = false}
 
     @Setup
     fun init() {
@@ -34,6 +37,16 @@ open class TwitterFeedBenchmark {
     @Benchmark
     fun decodeTwitter() = Json.decodeFromString(MacroTwitterFeed.serializer(), input)
 
+    @Benchmark
+    fun decodeTwitterNoAltNames() = jsonNoAltNames.decodeFromString(MacroTwitterFeed.serializer(), input)
+
     @Benchmark
     fun encodeTwitter() = Json.encodeToString(MacroTwitterFeed.serializer(), twitter)
+
+    @Benchmark
+    fun decodeMicroTwitter() = jsonIgnoreUnknwn.decodeFromString(MicroTwitterFeed.serializer(), input)
+
+    @Benchmark
+    fun decodeMicroTwitterNoAltNames() = jsonIgnoreUnknwnNoAltNames.decodeFromString(MicroTwitterFeed.serializer(), input)
+
 }

benchmark/src/jmh/kotlin/kotlinx/benchmarks/model/MacroTwitter.kt

@@ -9,6 +9,24 @@ data class MacroTwitterFeed(
     val search_metadata: SearchMetadata
 )
 
+@Serializable
+data class MicroTwitterFeed(
+    val statuses: List<TwitterReducedStatus>
+)
+
+@Serializable
+data class TwitterReducedStatus(
+    val metadata: Metadata,
+    val created_at: String,
+    val id: Long,
+    val id_str: String,
+    val text: String,
+    val source: String,
+    val truncated: Boolean,
+    val user: TwitterReducedUser,
+    val retweeted_status: TwitterReducedStatus? = null,
+)
+
 @Serializable
 data class TwitterStatus(
     val metadata: Metadata,
@@ -92,6 +110,24 @@ data class Metadata(
     val iso_language_code: String
 )
 
+@Serializable
+data class TwitterReducedUser(
+    val id: Long,
+    val id_str: String,
+    val name: String,
+    val screen_name: String,
+    val location: String,
+    val description: String,
+    val url: String?,
+    val entities: UserEntities,
+    val protected: Boolean,
+    val followers_count: Int,
+    val friends_count: Int,
+    val listed_count: Int,
+    val created_at: String,
+    val favourites_count: Int,
+)
+
 @Serializable
 data class TwitterUser(
     val id: Long,

core/commonMain/src/kotlinx/serialization/internal/PluginGeneratedSerialDescriptor.kt

@@ -97,8 +97,8 @@ internal open class PluginGeneratedSerialDescriptor(
     override fun hashCode(): Int = _hashCode
 
     override fun toString(): String {
-        return indices.entries.joinToString(", ", "$serialName(", ")") {
-            it.key + ": " + getElementDescriptor(it.value).serialName
+        return (0 until elementsCount).joinToString(", ", "$serialName(", ")") { i ->
+            getElementName(i) + ": " + getElementDescriptor(i).serialName
         }
     }
 }

docs/json.md

@@ -13,6 +13,7 @@ In this chapter we'll walk through various [Json] features.
   * [Pretty printing](#pretty-printing)
   * [Lenient parsing](#lenient-parsing)
   * [Ignoring unknown keys](#ignoring-unknown-keys)
+  * [Alternative Json names](#alternative-json-names)
   * [Coercing input values](#coercing-input-values)
   * [Encoding defaults](#encoding-defaults)
   * [Allowing structured map keys](#allowing-structured-map-keys)
@@ -151,6 +152,40 @@ Project(name=kotlinx.serialization)
 
 <!--- TEST -->
 
+### Alternative Json names
+
+It's not a rare case when JSON fields got renamed due to a schema version change or something else.
+Renaming JSON fields is available with [`@SerialName` annotation](basic-serialization.md#serial-field-names), but 
+such a renaming blocks ability to decode data with old name. 
+For the case when we want to support multiple JSON names for the one Kotlin property, there is a [JsonNames] annotation:
+
+```kotlin
+@Serializable
+data class Project(@JsonNames(["title"]) val name: String)
+
+fun main() {
+  val project = Json.decodeFromString<Project>("""{"name":"kotlinx.serialization"}""")
+  println(project)
+  val oldProject = Json.decodeFromString<Project>("""{"title":"kotlinx.coroutines"}""")
+  println(oldProject)
+}
+```
+
+> You can get the full code [here](../guide/example/example-json-04.kt).
+
+As you can see, both `name` and `title` Json fields correspond to `name` property:
+
+```text
+Project(name=kotlinx.serialization)
+Project(name=kotlinx.coroutines)
+```
+
+Support for [JsonNames] annotation is controlled via [JsonBuilder.useAlternativeNames] flag. 
+Unlike most of the configuration flags, this one is enabled by default and does not need attention 
+unless you want to do some fine-tuning.
+
+<!--- TEST -->
+
 ### Coercing input values
 
 JSON formats that are encountered in the wild can be flexible in terms of types and evolve quickly.
@@ -185,7 +220,7 @@ fun main() {
 }
 ```                                  
 
-> You can get the full code [here](../guide/example/example-json-04.kt).
+> You can get the full code [here](../guide/example/example-json-05.kt).
 
 We see that invalid `null` value for the `language` property was coerced into the default value.
 
@@ -219,7 +254,7 @@ fun main() {
 }
 ```                                  
 
-> You can get the full code [here](../guide/example/example-json-05.kt).
+> You can get the full code [here](../guide/example/example-json-06.kt).
 
 It produces the following output which encodes the values of all the properties:
 
@@ -251,7 +286,7 @@ fun main() {
 }
 ```                                  
 
-> You can get the full code [here](../guide/example/example-json-06.kt).
+> You can get the full code [here](../guide/example/example-json-07.kt).
 
 The map with structured keys gets represented as `[key1, value1, key2, value2,...]` JSON array.
 
@@ -282,7 +317,7 @@ fun main() {
 }
 ```                                   
 
-> You can get the full code [here](../guide/example/example-json-07.kt).
+> You can get the full code [here](../guide/example/example-json-08.kt).
 
 This example produces the following non-stardard JSON output, yet it is a widely used encoding for
 special values in JVM world.
@@ -316,7 +351,7 @@ fun main() {
 }  
 ```
 
-> You can get the full code [here](../guide/example/example-json-08.kt).
+> You can get the full code [here](../guide/example/example-json-09.kt).
 
 In combination with an explicitly specified [SerialName] of the class it provides full
 control on the resulting JSON object. 
@@ -348,7 +383,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-09.kt).
+> You can get the full code [here](../guide/example/example-json-10.kt).
 
 A `JsonElement` prints itself as a valid JSON.
 
@@ -391,7 +426,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-10.kt).
+> You can get the full code [here](../guide/example/example-json-11.kt).
 
 The above example sums `votes` in all objects in the `forks` array, ignoring the objects that have no `votes`, but 
 failing if the structure of the data is otherwise different.
@@ -430,7 +465,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-11.kt).
+> You can get the full code [here](../guide/example/example-json-12.kt).
 
 At the end, we get a proper JSON string.
 
@@ -459,7 +494,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-12.kt).
+> You can get the full code [here](../guide/example/example-json-13.kt).
 
 The result is exactly what we would expect.
 
@@ -536,7 +571,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-13.kt).
+> You can get the full code [here](../guide/example/example-json-14.kt).
 
 The output shows that both cases are correctly deserialized into a Kotlin [List].
 
@@ -588,7 +623,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-14.kt).
+> You can get the full code [here](../guide/example/example-json-15.kt).
 
 We end up with a single JSON object. 
 
@@ -633,7 +668,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-15.kt).
+> You can get the full code [here](../guide/example/example-json-16.kt).
 
 We can clearly see the effect of the custom serializer.
 
@@ -706,7 +741,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-16.kt).
+> You can get the full code [here](../guide/example/example-json-17.kt).
 
 No class discriminator is added in the JSON output.
 
@@ -802,7 +837,7 @@ fun main() {
 }
 ```
 
-> You can get the full code [here](../guide/example/example-json-17.kt).
+> You can get the full code [here](../guide/example/example-json-18.kt).
 
 This gives us fine-grained control on the representation of the `Response` class in our JSON output.
 
@@ -867,7 +902,7 @@ fun main() {
 }
 ```  
 
-> You can get the full code [here](../guide/example/example-json-18.kt).
+> You can get the full code [here](../guide/example/example-json-19.kt).
 
 ```text
 UnknownProject(name=example, details={"type":"unknown","maintainer":"Unknown","license":"Apache 2.0"})
@@ -904,6 +939,8 @@ The next chapter covers [Alternative and custom formats (experimental)](formats.
 [JsonBuilder.prettyPrint]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FprettyPrint%2F%23%2FPointingToDeclaration%2F
 [JsonBuilder.isLenient]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FisLenient%2F%23%2FPointingToDeclaration%2F
 [JsonBuilder.ignoreUnknownKeys]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FignoreUnknownKeys%2F%23%2FPointingToDeclaration%2F
+[JsonNames]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-names/index.html
+[JsonBuilder.useAlternativeNames]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FuseAlternativeNames%2F%23%2FPointingToDeclaration%2F
 [JsonBuilder.coerceInputValues]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FcoerceInputValues%2F%23%2FPointingToDeclaration%2F
 [JsonBuilder.encodeDefaults]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FencodeDefaults%2F%23%2FPointingToDeclaration%2F
 [JsonBuilder.allowStructuredMapKeys]: https://kotlin.github.io/kotlinx.serialization/kotlinx-serialization-json/kotlinx-serialization-json/kotlinx.serialization.json/-json-builder/index.html#kotlinx.serialization.json%2FJsonBuilder%2FallowStructuredMapKeys%2F%23%2FPointingToDeclaration%2F

docs/serialization-guide.md

@@ -106,6 +106,7 @@ Once the project is set up, we can start serializing some classes.
   * <a name='pretty-printing'></a>[Pretty printing](json.md#pretty-printing)
   * <a name='lenient-parsing'></a>[Lenient parsing](json.md#lenient-parsing)
   * <a name='ignoring-unknown-keys'></a>[Ignoring unknown keys](json.md#ignoring-unknown-keys)
+  * <a name='alternative-json-names'></a>[Alternative Json names](json.md#alternative-json-names)
   * <a name='coercing-input-values'></a>[Coercing input values](json.md#coercing-input-values)
   * <a name='encoding-defaults'></a>[Encoding defaults](json.md#encoding-defaults)
   * <a name='allowing-structured-map-keys'></a>[Allowing structured map keys](json.md#allowing-structured-map-keys)

formats/json/api/kotlinx-serialization-json.api

@@ -83,6 +83,7 @@ public final class kotlinx/serialization/json/JsonBuilder {
 	public final fun getPrettyPrint ()Z
 	public final fun getPrettyPrintIndent ()Ljava/lang/String;
 	public final fun getSerializersModule ()Lkotlinx/serialization/modules/SerializersModule;
+	public final fun getUseAlternativeNames ()Z
 	public final fun getUseArrayPolymorphism ()Z
 	public final fun isLenient ()Z
 	public final fun setAllowSpecialFloatingPointValues (Z)V
@@ -95,6 +96,7 @@ public final class kotlinx/serialization/json/JsonBuilder {
 	public final fun setPrettyPrint (Z)V
 	public final fun setPrettyPrintIndent (Ljava/lang/String;)V
 	public final fun setSerializersModule (Lkotlinx/serialization/modules/SerializersModule;)V
+	public final fun setUseAlternativeNames (Z)V
 	public final fun setUseArrayPolymorphism (Z)V
 }
 
@@ -190,6 +192,15 @@ public final class kotlinx/serialization/json/JsonKt {
 	public static synthetic fun Json$default (Lkotlinx/serialization/json/Json;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lkotlinx/serialization/json/Json;
 }
 
+public abstract interface annotation class kotlinx/serialization/json/JsonNames : java/lang/annotation/Annotation {
+	public abstract fun names ()[Ljava/lang/String;
+}
+
+public final class kotlinx/serialization/json/JsonNames$Impl : kotlinx/serialization/json/JsonNames {
+	public fun <init> ([Ljava/lang/String;)V
+	public final fun names ()[Ljava/lang/String;
+}
+
 public final class kotlinx/serialization/json/JsonNull : kotlinx/serialization/json/JsonPrimitive {
 	public static final field INSTANCE Lkotlinx/serialization/json/JsonNull;
 	public fun getContent ()Ljava/lang/String;

formats/json/commonMain/src/kotlinx/serialization/json/Json.kt

@@ -7,6 +7,7 @@ package kotlinx.serialization.json
 import kotlinx.serialization.*
 import kotlinx.serialization.json.internal.*
 import kotlinx.serialization.modules.*
+import kotlin.native.concurrent.*
 
 /**
  * The main entry point to work with JSON serialization.
@@ -52,9 +53,12 @@ public sealed class Json(internal val configuration: JsonConfiguration) : String
     override val serializersModule: SerializersModule
         get() = configuration.serializersModule
 
+    internal val schemaCache: DescriptorSchemaCache = DescriptorSchemaCache()
+
     /**
      * The default instance of [Json] with default configuration.
      */
+    @ThreadLocal // to support caching
     public companion object Default : Json(JsonConfiguration())
 
     /**
@@ -228,6 +232,14 @@ public class JsonBuilder internal constructor(configuration: JsonConfiguration)
      */
     public var allowSpecialFloatingPointValues: Boolean = configuration.allowSpecialFloatingPointValues
 
+    /**
+     * Switches whether Json instance make use of [JsonNames] annotation; enabled by default.
+     *
+     * Disabling this flag when one do not use [JsonNames] at all may sometimes result in better performance,
+     * particularly when a large count of fields is skipped with [ignoreUnknownKeys].
+     */
+    public var useAlternativeNames: Boolean = configuration.useAlternativeNames
+
     /**
      * Module with contextual and polymorphic serializers to be used in the resulting [Json] instance.
      */
@@ -255,7 +267,8 @@ public class JsonBuilder internal constructor(configuration: JsonConfiguration)
             encodeDefaults, ignoreUnknownKeys, isLenient,
             allowStructuredMapKeys, prettyPrint, prettyPrintIndent,
             coerceInputValues, useArrayPolymorphism,
-            classDiscriminator, allowSpecialFloatingPointValues, serializersModule
+            classDiscriminator, allowSpecialFloatingPointValues, useAlternativeNames,
+            serializersModule
         )
     }
 }