1 /* 2 * Copyright 2017-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. 3 */ 4 5 package kotlinx.serialization.json 6 7 import kotlinx.serialization.* 8 import kotlinx.serialization.descriptors.* 9 import kotlinx.serialization.encoding.* 10 import kotlinx.serialization.json.internal.* 11 import kotlin.native.concurrent.* 12 13 /** 14 * Indicates that the field can be represented in JSON 15 * with multiple possible alternative names. 16 * [Json] format recognizes this annotation and is able to decode 17 * the data using any of the alternative names. 18 * 19 * Unlike [SerialName] annotation, does not affect JSON encoding in any way. 20 * 21 * Example of usage: 22 * ``` 23 * @Serializable 24 * data class Project(@JsonNames("title") val name: String) 25 * 26 * val project = Json.decodeFromString<Project>("""{"name":"kotlinx.serialization"}""") 27 * println(project) // OK 28 * val oldProject = Json.decodeFromString<Project>("""{"title":"kotlinx.coroutines"}""") 29 * println(oldProject) // Also OK 30 * ``` 31 * 32 * This annotation has lesser priority than [SerialName]. 33 * In practice, this means that if property A has `@SerialName("foo")` annotation, and property B has `@JsonNames("foo")` annotation, 34 * Json key `foo` will be deserialized into property A. 35 * 36 * Using the same alternative name for different properties across one class is prohibited and leads to a deserialization exception. 37 * 38 * @see JsonBuilder.useAlternativeNames 39 */ 40 @SerialInfo 41 @Target(AnnotationTarget.PROPERTY) 42 @ExperimentalSerializationApi 43 public annotation class JsonNames(vararg val names: String) 44 45 /** 46 * Specifies key for class discriminator value used during polymorphic serialization in [Json]. 47 * Provided key is used only for an annotated class and its subclasses; 48 * to configure global class discriminator, use [JsonBuilder.classDiscriminator] 49 * property. 50 * 51 * This annotation is [inheritable][InheritableSerialInfo], so it should be sufficient to place it on a base class of hierarchy. 52 * It is not possible to define different class discriminators for different parts of class hierarchy. 53 * Pay attention to the fact that class discriminator, same as polymorphic serializer's base class, is 54 * determined statically. 55 * 56 * Example: 57 * ``` 58 * @Serializable 59 * @JsonClassDiscriminator("message_type") 60 * abstract class Base 61 * 62 * @Serializable // Class discriminator is inherited from Base 63 * abstract class ErrorClass: Base() 64 * 65 * @Serializable 66 * class Message(val message: Base, val error: ErrorClass?) 67 * 68 * val message = Json.decodeFromString<Message>("""{"message": {"message_type":"my.app.BaseMessage", "message": "not found"}, "error": {"message_type":"my.app.GenericError", "error_code": 404}}""") 69 * ``` 70 * 71 * @see JsonBuilder.classDiscriminator 72 */ 73 @InheritableSerialInfo 74 @Target(AnnotationTarget.CLASS) 75 @ExperimentalSerializationApi 76 public annotation class JsonClassDiscriminator(val discriminator: String) 77