Doc rewrite update 3 - Serialize built in types #3082
Conversation
| When you serialize Kotlin `Long` values to JSON, JavaScript's native number type can't represent the full range of a Kotlin `Long` type, | ||
| leading to precision loss. |
There was a problem hiding this comment.
Is it worthwhile to note that this is a limitation of JS, not Json that is effectively arbitrary precision? It is somewhat implied by the explanation below, but can be confusing in the distinction.
There was a problem hiding this comment.
Good point - it is a bit confusing - I restructured this part a bit:
Long numbers as strings
You can represent Long numbers as strings in JSON.
This is useful in JavaScript environments, where JavaScript's Number type can't precisely represent all Kotlin Long values, which may lead to precision loss.
Use LongAsStringSerializer with the @Serializable annotation to encode Long values as strings in JSON:
| > JSON doesn't natively support complex or composite keys. | ||
| > To encode structured objects as map keys, see [Encode structured map keys](serialization-json-configuration.md#encode-structured-map-keys). | ||
| > | ||
| {style="note"} |
There was a problem hiding this comment.
Maybe mention that other formats may support this in different ways.
There was a problem hiding this comment.
the focus is on JSON here — unless we specify how it differs I think it might be just stating the obvious here. (to me it would read like: In JSON it works like this. In other formats it might work differently.) But if we have a very critical difference here, then I think we could list it.
| //sampleStart | ||
| @Serializable | ||
| class Data( | ||
| @Serializable(with=LongAsStringSerializer::class) |
There was a problem hiding this comment.
I'd prefer removing explicit with: @Serializable(LongAsStringSerializer::class)
| > For more information, see [Specify serializers for a file](third-party-classes.md#specify-serializers-for-a-file). | ||
| > | ||
| {style="tip"} | ||
|
|
There was a problem hiding this comment.
I think it might worth it to add section aboun unsigned numbers here as well, given they're stable in stdlib and IR compiler has been default for years (https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/value-classes.md#unsigned-types-support-json-only). Just don't forget mentioning
Unsigned types are output as unsigned only in JSON format. Other formats such as ProtoBuf and CBOR use built-in serializers that use an underlying signed representation for unsigned types.
There was a problem hiding this comment.
Stating that unsigned is only unsigned in Json is inaccurate, other formats support unsigned directly (and at full range) - maybe something that the protobuf serializer can be extended to do.
|
|
||
| ### Collections | ||
|
|
||
| Kotlin Serialization supports collection types such as [`List`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/), [`Set`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-set/), and [`Map`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-map/). |
There was a problem hiding this comment.
I would rephrase this slightly. The thing is, we also support concrete implementations (e.g. ArrayList and LinkedHashSet), so our users should not have impression that only basic intrefaces are supported. Mutable counterparts should be mentioned as well.
And btw, regular Arrays and primitive Int/Long/...Array too.
| // [{"name":"kotlinx.serialization"},{"name":"kotlinx.coroutines"}] | ||
| } | ||
| //sampleEnd | ||
| ``` |
There was a problem hiding this comment.
Since Sets have their own section, maybe it is worth mentioning that
Duplicate entries in Sets do not cause exceptions on deserialization by default and behavior on duplicates is implementation-defined.
|
|
||
| #### Deserialization behavior of collections | ||
|
|
||
| Kotlin uses the declared type to deserialize JSON. |
There was a problem hiding this comment.
I think original
During deserialization, the type of the resulting object is determined by the static type that was specified in the source code—either as the type of the property or as the type parameter of the decoding function.
explains what happens better. It also answers the question "What happens if I specify ArrayList or LinkedList"
There was a problem hiding this comment.
Although you can mention this in the beginning of the section, add the suggested tip to the Set section and drop this section completely.
| > | ||
| {style="tip"} | ||
|
|
||
| ## Duration |
There was a problem hiding this comment.
We also have two new serializers for Instant btw (#2945). They probably should be mentioned here (and requirement for Kotlin 2.2)
There was a problem hiding this comment.
nice one 💯 I added it to this section, so now it should be
Duration and Instant
(added kotlin-min-compiler-version="2.2" to the example as well)
3 participants
This is the third part of the Kotlin Serialization rewrite.
Related YouTract ticket is: KT-80887 [Docs] Create a serialize built-in classes guide for kotlinx.serialization