1.7.3

This release aims to fix important issues that were discovered in the 1.7.2 release,
including the inability to sync certain projects into Android Studio/IntelliJ IDEA and exceptions from custom Uuid serializers.

It uses Kotlin 2.0.20 by default.

• Use explicit kotlin-stdlib and kotlin-test versions from version catalog (#2818)
• Drop usage of deprecated Any?.freeze() in K/N target (#2819)
• Check against serialName instead of simpleClassName (#2802)
• Ignore NoClassDefFoundError when initializing builtins map for serializer() function (#2803)
• Clarify example for SerializationException (#2806)

1.7.2

This release provides several new features, including a major Cbor configuration rework.
It uses Kotlin 2.0.20 by default.

Cbor feature set for COSE compliance

This change brings a lot of features to the CBOR format, namely:

• Serial Labels — see @CborLabel annotation and preferCborLabelsOverNames flag.
• Tagging of keys and values — see encode*Tags and verify*Tags set of flags
• Definite length encoding — see useDefiniteLengthEncoding. This flag affects object encoding, since decoding of arrays with definite lenghts is automatically supported.
• Option to globally prefer major type 2 for byte array encoding — see alwaysUseByteString flag.

Since there are quite a lot of flags now, they were restructured to a separate CborConfiguration class, similarly to JsonConfiguration. It is possible to retrieve this configuration from CborEncoder/CborDecoder interfaces in your custom serializers (see their documentation for details).

All of these features make it possible to serialize and parse COSE-compliant CBOR, for example, ISO/IEC 18013-5:2021-compliant mobile driving license data. In case you want to make use of them, there is a predefined Cbor.CoseCompliant instance.
However, some canonicalization steps (such as sorting keys) still need to be performed manually.

This functionality was contributed to us by Bernd Prünster and Christian.

Keeping generated serializers

One of the most requested features for serialization plugin was to continue to generate a serializer even if a custom one is specified for the class. It allows using a plugin-generated serializer in a fallback or delegate strategy, accessing type structure via descriptor, using default serialization behavior in inheritors that do not use custom serializers.

Starting with this release, you can specify the @KeepGeneratedSerializer annotation on the class declaration to instruct the plugin to continue generating the serializer. In this case, the serializer will be accessible using the .generatedSerializer() function on the class's companion object.

This annotation is currently experimental. Kotlin 2.0.20 or higher is required for this feature to work.

You can check out the examples in the documentation and in the PRs: #2758, #2669.

Serializer for kotlin.uuid.Uuid

Kotlin 2.0.20 added a common class to represent UUIDs in a multiplatform code. kotlinx.serialization 1.7.2 provides a corresponding Uuid.serializer() for it, making it possible to use it in @Serializable classes.

Note that for now, serializer should be provided manually with @Contextual annotation. Plugin will be able to automatically insert Uuid serializer in Kotlin 2.1.0.

See more details in the corresponding PR.

Other bugfixes and improvements

• Prohibited using of zero and negative field numbers in ProtoNumber (#2766)
• Improve readability of protobuf decoding exception messages (#2768) (thanks to xiaozhikang0916)
• docs(serializers): Fix grammatical errors (#2779) (thanks to jamhour1g)
• Fixed VerifyError after ProGuard optimization (#2728)
• Add wasm-wasi target to Okio integration (#2727)

1.7.1

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.

Fixed HOCON publication

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.

Add integration with a kotlinx-io library

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.

Other bugfixes

• Prohibited use of elements other than JsonObject in JsonTransformingSerializer with polymorphic serialization (#2715)

1.7.0

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).

1.7.0-RC

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.

Important change: priority of PolymorphicSerializer for interfaces during call to serializer() function

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.

Json configuration flag to allow commentaries

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.

Promote JsonConfiguration.explicitNulls to a stable API

This 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 ProtoBuf

oneof 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.

Other improvements and bugfixes

• Update okio to 3.9.0 version (#2671)
• Add extension to access original descriptor from one made with SerialDescriptor.nullable (#2633) (thanks to Chuckame)
• Use @SerialName of inline polymorphic children in Json (#2601) (thanks to Tad Fisher)
• Fix serializing nulls for a property of a parameterized type with a nullable upper bound with Protobuf (#2561) (thanks to Shreck Ye)
• Fixed type discriminator value for custom serializer that uses encodeJsonElement (#2628)
• Refine exception messages in case of deserializing data from JsonElement. (#2648)

1.6.3

This release provides a couple of new features and uses Kotlin 1.9.22 as default.

Class discriminator output mode

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.

Other features

• Add kebab-case naming strategy (#2531) (thanks to Emil Kantis)
• Add value class support to the ProtoBufSchemaGenerator (#2542) (thanks to Felipe Rotilho)

Bugfixes and improvements

• Fix: Hocon polymorphic serialization in containers (#2151) (thanks to LichtHund)
• Actualize lenient mode documentation (#2568)
• Slightly improve error messages thrown from serializer() function (#2533)
• Do not try to coerce input values for properties (#2530)
• Make empty objects and arrays collapsed in pretty print mode (#2506)
• Update Gradle dokka configuration to make sure "source" button is visible in all API docs (#2518, #2524)

1.6.2

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.

• Add Wasm WASI target (#2510)
• Bring back linuxArm32Hfp target because it is deprecated, but not removed yet. (#2505)

1.6.1

This release uses Kotlin 1.9.20 by default, while upcoming 1.9.21 is also supported.

Trailing commas in Json

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.

Support of WasmJs target

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.

Bugfixes and improvements

• Fix TaggedDecoder nullable decoding (#2456) (thanks to Phillip Schichtel)
• Fix IllegalAccessException for some JPMS boundaries (#2469)
• Cbor: check if inline value classes are marked as @ByteString (#2466) (thanks to eater)
• Improve polymorphic deserialization optimization (#2481)
• Update Okio dependency to 3.6.0 (#2473)
• Add protobuf conformance tests (#2404) (thanks to Doğaç Eldenk)
• Support decoding maps with boolean keys (#2440)

1.6.0

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.

Bugfixes

• Improve error messages from Json parser (#2406)
• Mark @SerialName, @Required and @Transient with @MustBeDocumented (#2407)
• Ensure that no additional files except java compiler output get into multi-release jar (#2405)
• Fix enums with negative numbers in protobuf not serializing & de-serializing (#2400) (thanks to Doğaç Eldenk)

1.6.0-RC

This release is based on the Kotlin 1.9.0.

Removal of Legacy JS target

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.

Case insensitivity for enums in Json

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.

Other bugfixes and enhancements

• Add support to decode numeric literals containing an exponent (#2227) (thanks to Roberto Blázquez)
• Fix NoSuchMethodError related to Java 8 API compatibility (#2328, #2350) (thanks to Björn Kautler)
• Changed actual FormatLanguage annotation for JS and Native to avoid problems with duplicating org.intellij.lang.annotations.Language (#2390, #2379)
• Fix error triggered by 'consume leading class discriminator' polymorphic parsing optimization (#2362)
• Fix runtime error with Serializer for Nothing on the JS target (#2330) (thanks to Shreck Ye)
• Fix beginStructure in JsonTreeDecoder when inner structure descriptor is same as outer (#2346) (thanks to Ugljesa Jovanovic)
• Actualize 'serializer not found' platform-specific message (#2339)
• Fixed regression with serialization using a list parametrized with contextual types (#2331)