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)

1.5.1

This release contains an important Native targets overhaul, as well as numerous enhancements and bugfixes.
Kotlin 1.8.21 is used by default.

New set of Native targets

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.

Improvements in Json elements

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.

Other enhancements

• Potential source-breaking change: Rename json-okio target variables to sink (#2226)
• Function to retrieve KSerializer by KClass and type arguments serializers (#2291)
• Added FormatLanguage annotation to Json methods (#2234)
• Properties Format: Support sealed/polymorphic classes as class properties (#2255)

Bugfixes

• KeyValueSerializer: Fix missing call to endStructure() (#2272)
• ObjectSerializer: Respect sequential decoding (#2273)
• Fix value class encoding in various corner cases (#2242)
• Fix incorrect json decoding iterator's .hasNext() behavior on array-wrapped inputs (#2268)
• Fix memory leak caused by invalid KTypeWrapper's equals method (#2274)
• Fixed NoSuchMethodError when parsing a JSON stream on Java 8 (#2219)
• Fix MissingFieldException duplication (#2213)

1.5.0

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.

HoconEncoder and HoconDecoder interfaces and HOCON-specific serializers

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!

Ability to read buffered huge strings in custom Json deserializers

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.

Bugfixes

• Improve runtime exceptions messages (#2180)
• Added support for null values for nullable enums in lenient mode (#2176)
• Prevent class loaders from leaking when using ClassValue cache (#2175)

1.5.0-RC

This is a release candidate for the next version with many new features to try.
It uses Kotlin 1.8.0 by default.

Json naming strategies

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.

Json unquoted literals

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.

Stabilization of serializer(java.lang.Type) function family

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.

Deprecations in module builders for polymorphism

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.

Bundled Proguard rules

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.

Support for kotlin.Duration in HOCON format

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.

Functional and performance improvements

• Make DeserializationStrategy covariant at declaration-site (#1897) (thanks to Lukellmann)
• Added support for the kotlin.Nothing class as built-in (#1991, #2150)
• Further improve stream decoding performance (#2101)
• Introduce CharArray pooling for InputStream decoding (#2100)
• Consolidate exception messages and improve them (#2068)

Bugfixes

• Add stable hashCode()/equals() calculation to PrimitiveSerialDescriptor (#2136) (thanks to Vasily Vasilkov)
• Added a factory that creates an enum serializer with annotations on the class (#2125)
• Correctly handle situation where different serializers can be provided for the same KClass in SealedClassSerializer (#2113)
• Fixed serializers caching for parametrized types from different class loaders (#2070)

1.4.1

This patch release contains several bug fixes and improvements.
Kotlin 1.7.20 is used by default.

Improvements

• Add @MustBeDocumented to certain annotations (#2059)
• Deprecate .isNullable in SerialDescriptor builder (#2040)
• Unsigned primitives and unsigned arrays serializers can be retrieved as built-ins (#1992)
• Serializers are now cached inside reflective lookup, leading to faster serializer retrieval (#2015)
• Compiler plugin can create enum serializers using static factories for better speed (#1851) (Kotlin 1.7.20 required)
• Provide a foundation for compiler plugin intrinsics available in Kotlin 1.8.0 (#2031)

Bugfixes

• Support polymorphism in Properties format (#2052) (thanks to Rodrigo Vedovato)
• Added support of UTF-16 surrogate pairs to okio streams (#2033)
• Fix dependency on core module from HOCON module (#2020) (thanks to Osip Fatkullin)

1.4.0

This release contains all features and bugfixes from 1.4.0-RC plus some bugfixes on its own (see below).
Kotlin 1.7.10 is used as a default.

Bugfixes

• Fixed decoding of huge JSON data for okio streams (#2006)