How to set the descriptor for deserializers that accept different representations for a data object?

[sschuberth]

I've written a deserializer that, in short, accepts both

description:
  name: hello

and

description: hello

In both cases the result object is

data class Description(
    val name: String? = null,
    val url: String? = null,
    val path: String? = null,
    @SerialName("resolved-ref")
    val resolvedRef: String? = null,
    val relative: Boolean? = null,
    val sha256: String? = null
)

The deserialize() code is

override fun deserialize(decoder: Decoder): Description {
    require(decoder is YamlInput) {
        "Only YAML input is supported."
    }

    val result = when (val node = decoder.node) {
        is YamlScalar -> Description(name = node.content)
        else -> Description.generatedSerializer().deserialize(decoder)
    }

    return result
}

By experimenting, I found out that in order for the deserialization process to not fail even before the above deserialize() is called, I need to set the descriptor to

override val descriptor: SerialDescriptor by lazy {
    val serialName = checkNotNull(Description::class.qualifiedName)

    // The YAML implementation requires a contextual descriptor, or otherwise `deserialize()` is not even called.
    @OptIn(InternalSerializationApi::class)
    buildSerialDescriptor(serialName, SerialKind.CONTEXTUAL) {
        element("object", Description.generatedSerializer().descriptor)
        element("string", PrimitiveSerialDescriptor("description", PrimitiveKind.STRING))
    }
}

However, that code has some issues:

• buildSerialDescriptor is internal API and should not be used anymore.
• To my understanding, the use of SerialKind.CONTEXTUAL is wrong as it's not a contextual serializer how KxS defines it, meaning that a serializer would be selected at runtime and be configured as part of SerializersModule.

Actually, my understanding of the descriptor is that it should describe the structure of the type produced by this (de-)serializer, and not all possible input "shapes". So in this case, I would only need to describe the Description type, i.e. I should be able to use the descriptor of the generated serializer for that class via delegation.

However, if I do so, I get this error

Value for 'packages' is invalid: Value for 'info' is invalid: Value for 'description' is invalid: Expected an object, but got a scalar value
InvalidPropertyValueException at packages.info.description on line 4, column 18: Value for 'packages' is invalid: Value for 'info' is invalid: Value for 'description' is invalid: Expected an object, but got a scalar value

and the deserialize() function is not even called.

Any hints what's going on here? Is my understanding of the purpose of the descriptor wrong? How can I get rid of the need for the internal buildSerialDescriptor?

Thanks for any insights!