Kotlin multiplatform / multi-format serialization
APACHE-2.0 License
Bot releases are hidden (Show)
This is a bugfix release that aims to fix missing kotlinx-serialization-hocon
artifact.
It also contains experimental integration with kotlinx-io
library.
Kotlin 2.0.0 is used by default.
Sadly, 1.7.0 release was published incomplete: kotlinx-serialization-hocon
artifact is missing from 1.7.0 and 1.7.0-RC releases.
This release fixes this problem and now kotlinx-serialization-hocon
is available again with 1.7.1 version.
No other changes were made to this artifact. Related ticket: #2717.
kotlinx-io
is an official multiplatform library that provides basic IO primitives, similar to Okio.
kotlinx.serialization integration is now available in a separate artifact, located at the kotlinx-serialization-json-io
coordinates. Integration artifact provides functions similar to existing Okio integration: encodeToSink
, decodeFromSource
, and decodeSourceToSequence
. Check out the PR for more details.
Published by sandwwraith 4 months ago
This release contains all of the changes from 1.7.0-RC and is compatible with Kotlin 2.0.
Please note that for reasons explained in the 1.7.0-RC changelog, it may not be possible to use it with the Kotlin 1.9.x
compiler plugin. Yet, it is still fully backward compatible with previous versions.
The only difference with 1.7.0-RC is that the classDiscriminatorMode
property in JsonBuilder
is marked as experimental,
as it should have been when it was introduced (#2680).
Published by sandwwraith 5 months ago
This is a release candidate for the next version. It is based on Kotlin 2.0.0-RC3 and is fully compatible with a stable Kotlin 2.0 release.
Due to a potential breaking change (see below), it requires a compiler plugin with a version at least of 2.0.0-RC1.
Non-sealed interfaces in kotlinx.serialization are always serializable with a polymorphic serializer,
even if they do not have @Serializable
annotation. This also means that serializersModule.serializer<SomeInterface>()
call will return you a serializer capable of polymorphism. This function was written in a way that it unconditionally returns a PolymorphicSerializer
if type argument is a non-sealed interface. This caused problems with SerializersModule
functionality, because actual module was not taken into consideration, and therefore it was impossible to override serializer for interface using 'contextual serialization' feature. The problem is described in detail here. To overcome these problems, we had to change the behavior of this function regarding interfaces. It now looks into SerializersModule
first if T
is a non-sealed interface, and only if there is no registered contextual serializer for T
, it returns a polymorphic serializer.
Behavior before 1.7.0-RC:
interface SomeInterface
val module = SerializersModule {
contextual(SomeInterface::class, CustomSomeInterfaceSerializer)
}
// Prints PolymorphicSerializer<SomeInterface>:
println(module.serializer<SomeInterface>())
Behavior in 1.7.0-RC, 1.7.0, and higher:
interface SomeInterface
val module = SerializersModule {
contextual(SomeInterface::class, CustomSomeInterfaceSerializer)
}
// Prints CustomSomeInterfaceSerializer:
println(module.serializer<SomeInterface>())
We expect minimal impact from this change, but be aware of it anyway.
Implementation details are available in this PR.
Due to the serializer() function being also a compiler intrinsic, code
of kotlinx.serialization compiler plugin also accommodates this change in the 2.0 branch. To get a consistent result from both plugin and runtime, kotlinx.serialization compiler plugin should be at least of 2.0.0-RC1 version.
To verify so, 1.7.0-RC runtime will be rejected by older plugins.
While JSON standard does not allow any kind of commentaries, they are one of the most popular extensions — for example, commentaries are widely used in configuration files. To support this use-case, we added a new configuration flag, allowComments
. This flag allows the parser to skip over C/Java-style commentaries in JSON input. Note that commentaries cannot affect decoding or encoding in any way and are not stored anywhere. See details in the PR.
JsonConfiguration.explicitNulls
to a stable APIThis configuration flag has been around for a long time and got positive feedback. Therefore, we are promoting it to a stable state. It also received functionality enhancements when used with JsonConfiguration.coerceInputValues
(#2586). See related PR for details.
oneof
support in ProtoBufoneof
fields in protobuf messages represent a set of optional fields, where the only one of them is present. With the help of the new @ProtoOneOf
annotation, you can naturally map them to Kotlin's sealed class hierarchy. Check out the comprehensive guide for this feature here.
This functionality was contributed to us by xzk.
encodeJsonElement
(#2628)Published by sandwwraith 8 months ago
This release provides a couple of new features and uses Kotlin 1.9.22 as default.
Class discriminator provides information for serializing and deserializing polymorphic class hierarchies.
In case you want to encode more or less information for various third party APIs about types in the output, it is possible to control
addition of the class discriminator with the JsonBuilder.classDiscriminatorMode
property.
For example, ClassDiscriminatorMode.NONE
does not add class discriminator at all, in case the receiving party is not interested in Kotlin types.
You can learn more about this feature in the documentation and corresponding PR.
Published by sandwwraith 11 months ago
This is a patch release accompanying Kotlin 1.9.21. It also provides additional targets that were not available in 1.6.1: wasm-wasi
and (deprecated) linuxArm32Hfp
.
Published by sandwwraith 11 months ago
This release uses Kotlin 1.9.20 by default, while upcoming 1.9.21 is also supported.
Trailing commas are one of the most popular non-spec Json variations. A new configuration flag, allowTrailingComma
, makes Json parser accept them instead of throwing an exception. Note that it does not affect encoding, so kotlinx.serialization always produces Json without trailing commas. See details in the corresponding PR.
Kotlin/Wasm has been experimental for some time and gained enough maturity to be added to the kotlinx libraries. Starting with 1.6.1, kotlinx.serialization provides a wasm-js flavor, so your projects with Kotlin/Wasm can have even more functionality. As usual, just add serialization dependencies to your build and declare wasmJs target. Please remember that Kotlin/Wasm is still experimental, so changes are expected.
@ByteString
(#2466) (thanks to eater)Published by sandwwraith about 1 year ago
This release contains all features and bugfixes from 1.6.0-RC plus some bugfixes on its own (see below).
Kotlin 1.9.0 is used as a default, while 1.9.10 is also supported.
@SerialName
, @Required
and @Transient
with @MustBeDocumented
(#2407)Published by sandwwraith about 1 year ago
This release is based on the Kotlin 1.9.0.
Some time ago, in Kotlin 1.8, JS IR compiler was promoted to stable and old JS compiler was deprecated.
Kotlin 1.9 promotes the usage of deprecated JS compiler to an error. As a result, kotlinx.serialization no longer builds with the legacy compiler and does not distribute artifacts for it. You can read the migration guide for JS IR compiler here.
Also pay attention to the fact that Kotlin/Native also has some deprecated targets that are going to be removed in the Kotlin 1.9.20. Therefore, kotlinx.serialization 1.6.0-RC and 1.6.0 are likely the last releases that support these targets.
This release features a new configuration flag for Json: decodeEnumsCaseInsensitive
that allows you to decode enum values in a case-insensitive manner.
For example, when decoding enum class Foo { VALUE_A , VALUE_B}
both inputs "value_a"
and "value_A"
will yield Foo.VALUE_A
. You can read more about this feature in the documentation and corresponding PR.
Published by sandwwraith over 1 year ago
This release contains an important Native targets overhaul, as well as numerous enhancements and bugfixes.
Kotlin 1.8.21 is used by default.
The official Kotlin target support policy has recently been published describing new target policy: each target belongs to a certain tier, and different tiers have different stability guarantees. The official recommendation for library authors is to support targets up to Tier 3, and kotlinx.serialization now follows it. It means that in this release, there are a lot of new targets added from this tier, such as androidNativeX86
or watchosDeviceArm64
. Note that since they belong to Tier 3, they're not auto-tested on CI.
kotlinx.serialization also ships some deprecated Kotlin/Native targets that do not belong to any tier (e.g. iosArm32
, mingwX86
).
We'll continue to release them, but we do not provide support for them, nor do we plan to add new targets from the deprecated list.
There are two new function sets that should make creating raw Json elements easier.
First one contains overloads for JsonPrimitive
constructor-like function that accept unsigned types: JsonPrimitive(1u)
.
Second one adds new addAll
functions to JsonArrayBuilder
to be used with collections of numbers, booleans or strings: buildJsonArray { addAll(listOf(1, 2, 3)) }
.
Both were contributed to us by aSemy.
target
variables to sink
(#2226)Published by sandwwraith over 1 year ago
This release contains all features and bugfixes from 1.5.0-RC plus some experimental features and bugfixes on its own (see below).
Kotlin 1.8.10 is used as a default.
These interfaces work in a way similar to JsonEncoder
and JsonDecoder
: they allow intercepting (de)serialization process,
making writing if custom HOCON-specific serializers easier. New ConfigMemorySizeSerializer
and JavaDurationSerializer
already make use of them.
See more details in the PR.
Big thanks to Alexander Mikhailov for contributing this!
New interface ChunkedDecoder
allows you to read huge strings that may not fit in memory by chunks.
Currently, this interface is only implemented by Json decoder that works with strings and streams,
but we may expand it later, if there's a demand for it.
See more details in the PR authored by Alexey Sviridov.
Published by sandwwraith over 1 year ago
This is a release candidate for the next version with many new features to try.
It uses Kotlin 1.8.0 by default.
A long-awaited feature (#33) is available in this release.
A new interface, JsonNamingStrategy
and Json configuration property namingStrategy
allow
defining a transformation that is applied to all properties' names serialized by a Json instance.
There's also a predefined implementation for the most common use case: Json { namingStrategy = JsonNamingStrategy.SnakeCase }
.
Check out the PR for more details and documentation.
kotlinx-serialization-json has an API for manipulating raw Json values: functions and classes JsonObject
, JsonPrimitive
, etc.
In this release, there is a new addition to this API: JsonUnquotedLiteral
constructor function.
It allows to produce a string that is not quoted in the Json output. This function has a lot of valuable
applications: from writing unsigned or large numbers to embedding whole Json documents without the need for re-parsing.
For an example, read the Encoding literal Json content docs.
This huge feature was contributed to us by aSemy: #2041.
Functions serializer
, serializerOrNull
and extensions SerializersModule.serializer
, SerializersModule.serializerOrNull
have JVM-only overloads that accept java.lang.Type
. These overloads are crucial for interoperability: with them, third-party Java frameworks
like Spring, which usually rely on Java's reflection and type tokens, can retrieve KSerializer
instance and use kotlinx.serialization properly.
We've removed @ExperimentalSerializationApi
from these functions, and starting from 1.5.0-RC they're considered stable with all backward compatibility guarantees.
This change should improve third-party support for kotlinx.serialization in various frameworks.
See the PR for details.
Some time ago, in 1.3.2, new functions SerializersModuleBuilder.polymorphicDefaultSerializer/polymorphicDefaultDeserializer
and PolymorphicModuleBuilder.defaultDeserializer
were introduced
— better names allow an easier understanding of which serializers affect what part of the process.
In 1.5.0-RC, we finish the migration path: these functions are no longer experimental.
And old functions, namely SerializersModuleCollector.polymorphicDefault
and PolymorphicModuleBuilder.default
, are now deprecated.
See the PR for details.
The kotlinx-serialization-core-jvm
JAR file now includes consumer Proguard rules,
so manual Proguard configuration is no longer necessary for most of the setups.
See updated Android setup section and corresponding PRs: #2092, #2123.
HOCON specifies its own formatting for duration values. Starting with this release,
kotlinx-serialization-hocon is able to serialize and deserialize kotlin.Duration
using proper representation instead of the default one. Big thanks to Alexander Mikhailov
and his PRs: #2080, #2073.
kotlin.Nothing
class as built-in (#1991, #2150)Published by sandwwraith almost 2 years ago
This patch release contains several bug fixes and improvements.
Kotlin 1.7.20 is used by default.
Published by sandwwraith about 2 years ago
This is a candidate for the next big release with many new exciting features to try.
It uses Kotlin 1.7.10 by default.
Okio library by Square is a popular solution for fast and efficient IO operations on JVM, K/N and K/JS.
In this version, we have added functions that parse/write JSON directly to Okio's input/output classes, saving you the overhead of copying data to String
beforehand.
These functions are called Json.decodeFromBufferedSource
and Json.encodeToBufferedSink
, respectively.
There's also decodeBufferedSourceToSequence
that behaves similarly to decodeToSequence
from Java streams integration, so you can lazily decode multiple objects the same way as before.
Note that these functions are located in a separate new artifact, so users who don't need them wouldn't find themselves dependent on Okio.
To include this artifact in your project, use the same group id org.jetbrains.kotlinx
and artifact id kotlinx-serialization-json-okio
.
To find out more about this integration, check new functions' documentation and corresponding pull requests:
#1901 and #1982.
Inline classes and unsigned number types have been promoted to a Stable feature in Kotlin 1.5,
and now we are promoting support for them in kotlinx.serialization to Stable status, too.
To be precise, we've removed all @ExperimentalSerializationApi
annotations from functions related to inline classes encoding and decoding,
namely SerialDescriptor.isInline
, Encoder.encodeInline
, and some others. We've also updated related documentation article.
Additionally, all @ExperimentalUnsignedTypes
annotations were removed completely,
so you can freely use types such as UInt
and their respective serializers as a stable feature
without opt-in requirement.
When kotlinx.serialization 1.0 was released, all subclasses of SerializationException
were made internal,
since they didn't provide helpful information besides the standard message.
Since then, we've received a lot of feature requests with compelling use-cases for exposing some of these internal types to the public.
In this release, we are starting to fulfilling these requests by making MissingFieldException
public.
One can use it in the catch
clause to better understand the reasons of failure — for example, to return 400 instead of 500 from an HTTP server — and then use its fields
property to communicate the message better.
See the details in the corresponding PR.
In future releases, we'll continue work in this direction, and we aim to provide more useful public exception types & properties.
In the meantime, we've revamped KDoc for some methods regarding the exceptions — all of them now properly declare which exception types are allowed to be thrown.
For example, KSerializer.deserialize
is documented to throw IllegalStateException
to indicate problems unrelated to serialization, such as data validation in classes' constructors.
This release introduces a new @MetaSerializable
annotation that adds @Serializable
behavior to user-defined annotations — i.e., those annotations would also instruct the compiler plugin to generate a serializer for class. In addition, all annotations marked with @MetaSerializable
are saved in the generated @SerialDescriptor
as if they are annotated with @SerialInfo
.
This annotation will be particularly useful for various format authors who require adding some metadata to the serializable class — this can now be done using a single annotation instead of two, and without the risk of forgetting @Serializable
. Check out details & examples in the KDoc and corresponding PR.
Note: Kotlin 1.7.0 or higher is required for this feature to work.
As a part of a coordinated effort to unify kotlinx libraries users' experience, Dokka-generated documentation pages (KDoc) were moved from https://kotlin.github.io/kotlinx.serialization/ to https://kotlinlang.org/api/kotlinx.serialization/. No action from you is required — there are proper redirects at the former address, so there is no need to worry about links in your blogpost getting obsolete or broken.
Note that this move does not affect guides written in Markdown in the docs
folder. We aim to move them later, enriching text with runnable examples as in the Kotlin language guides.
kotlin.time.Duration
class (plugin support comes in Kotlin 1.7.20) (#1960)Published by sandwwraith over 2 years ago
This release contains support for Protocol Buffers packed fields, as well as several bugfixes.
It uses Kotlin 1.6.21 by default.
It is now possible to encode and decode Kotlin classes to/from Protobuf messages with packed repeated fields.
To mark the field as packed, use @ProtoPacked
annotation on it.
Note it affects only List
and primitive collection such as IntArray
types.
With this feature, it is now possible to decode Proto3 messages, where all repeated fields are packed by default.
Protobuf schema generator also supports new @ProtoPacked
annotation.
Many thanks to Paul de Vrieze for his valuable contribution!
Collection<E>
properties that are not lists at the runtime (#1821)Published by sandwwraith almost 3 years ago
This release contains several features and bugfixes for core API as well as for HOCON format.
It uses Kotlin 1.6.10 by default.
It's now possible to encode Kotlin objects to Config
values with new Hocon.encodeToConfig
function.
This feature may help edit existing configs inside Kotlin program or generate new ones.
Big thanks to Osip Fatkullin for implementing this.
As of now, polymorphicDefault
clause inside SerializersModule { }
builder specifies a
fallback serializer to be used only during deserialization process. A new function has been introduced to allow setting
fallback serializer for serialization: polymorphicDefaultSerializer
.
This function should ease serializing vast hierarchies of third-party or Java classes.
Note that there are two new experimental functions, polymorphicDefaultSerializer
and polymorphicDefaultDeserializer
.
To avoid naming confusion, we are going to deprecate polymorphicDefault
in favor of polymorphicDefaultDeserializer
in the next minor release (1.4.0).
Credit for the PR goes to our contributor Joseph Burton.
Published by sandwwraith almost 3 years ago
This release mainly contains bugfixes for 1.3.0 and provides new experimental Json.decodeToSequence
function.
Published by sandwwraith about 3 years ago
This release contains all of the cool new features from 1.3.0-RC as well as minor improvements.
It uses Kotlin 1.5.31 by default.
Published by sandwwraith about 3 years ago
This is a release candidate for the next version. It contains a lot of interesting features and improvements,
so we ask you to evaluate it and share your feedback.
Kotlin 1.5.30 is used by default.
Finally, in kotlinx.serialization
1.3.0 we’re presenting the first experimental version of the serialization API for IO streams:
Json.encodeToStream
and Json.decodeFromStream
extension functions.
With this API, you can decode objects directly from files, network connections, and other data sources without reading the data to strings beforehand.
The opposite operation is also available: you can send encoded objects directly to files and other streams in a single API call.
IO stream serialization is available only on the JVM platform and for the JSON format for now.
Check out more in the PR.
Previous versions of the library allowed to specify whether to encode or drop default properties values with
format configuration flags such as Json { encodeDefaults = false }
.
In 1.3.0 we’re extending this feature by adding a new way to fine-tune the serialization of default values:
you can now control it on the property level using the new @EncodeDefault
annotation.
@EncodeDefault
annotation has a higher priority over the encodeDefaults
property and takes one of two possible values:
ALWAYS
(default value) encodes a property value even if it equals to default.NEVER
doesn’t encode the default value regardless of the format configuration.Encoding of the annotated properties is not affected by encodeDefaults
format flag
and works as described for all serialization formats, not only JSON.
To learn more, check corresponding PR.
In 1.3.0, we’re introducing one more way to reduce the size of the generated JSON strings: omitting null values.
A new JSON configuration property explicitNulls
defines whether null
property values should be included in the serialized JSON string.
The difference from encodeDefaults
is that explicitNulls = false
flag drops null values even if the property does not have a default value.
Upon deserializing such a missing property, a null
or default value (if it exists) will be used.
To maintain backwards compatibility, this flag is set to true
by default.
You can learn more in the documentation or the PR.
In previous versions, you could change the discriminator name using the
classDiscriminator property of the Json
instance.
In 1.3.0, we’re adding a way to set a custom discriminator name for each class hierarchy to enable more flexible serialization.
You can do it by annotating a class with @JsonClassDiscriminator
with the discriminator name as its argument.
A custom discriminator is applied to the annotated class and its subclasses.
Only one custom discriminator can be used in each class hierarchy, thanks to the new @InheritableSerialInfo
annotation.
Check out corresponding PR for details.
Now all kotlinx.serialization runtime libraries are shipped as a multi-release JAR with module-info.class
file for Java versions 9 and higher.
This enables possibilities to use kotlinx.serialization with modern tools such as jlink
and various technologies such as TorandoFX
.
Many thanks to our contributor Gerard de Leeuw and his PR for making this possible.
This release includes klibs for new targets, introduced in Kotlin/Native 1.5.30 —
macosArm64
, iosSimulatorArm64
, watchosSimulatorArm64
, and tvosSimulatorArm64
.
@SerialInfo
annotations in IR compilerPublished by sandwwraith over 3 years ago
This release contains various bugfixes, some useful features and important performance improvements.
It also uses Kotlin 1.5.20 as default.
@JsonNames
and coerceInputValues
in Json.decodeFromDynamic
(#1479)JsonStringBuilder
slow-path to avoid excessive array-copies for large strings with escape symbols (#1491)JsonDecodingException
instead of ClassCastException
during unexpected null in TreeJsonDecoder
(#1550)serialDescriptor<KType>
in production sources (#1540)DescriptorSchemaCache
in Json thread-local on Native (#1484)