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.
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.
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.
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.
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.
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)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.
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)This is patch release contains several bugfixes and improvements. Kotlin 1.7.20 is used by default.
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.
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)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)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.
This release mainly contains bugfixes for 1.3.0 and provides new experimental Json.decodeToSequence function.
This release contains all of the cool new features from 1.3.0-RC (see below) as well as minor improvements. It uses Kotlin 1.5.31 by default.
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 @EncodeDefaults annotation.
@EncodeDefaults 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 encodeDefault 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 compilerThis 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)This release mainly contains bugfixes for various issues, including important broken thread-safety and improper encoding.
This release has some known critical bugs, so we advise to use 1.2.1 instead.
This release contains a lot of new features and important improvements listed below; Kotlin 1.5.0 is used as a default compiler and language version.
JSON encoder and decoder were revisited and significantly rewritten, which lead us to up to 2-3x times speedup in certain cases. Additional details can be found in the corresponding issues: [1], [2].
The one of the most voted issues is fixed now — it is possible to specify multiple names for one property using new @JsonNames annotation. Unlike @SerialName, it only affects JSON decoding, so it is useful when dealing with different versions of the API. We've prepared a documentation for you about it.
JsonConfiguration is exposed as a property of Json instance. You can use it to adjust behavior in your custom serializers. Check out more in the corresponding issue and the PR.
Our implementation of Protocol Buffers format uses @Serializable Kotlin classes as a source of schema. This is very convenient for Kotlin-to-Kotlin communication, but makes interoperability between languages complicated. To resolve this issue, we now have a schema generator that can produce .proto files out of Kotlin classes. Using it, you can keep Kotlin classes as a source of truth and use traditional protoc compilers for other languages at the same time. To learn more, check out the documentation for the new ProtoBufSchemaGenerator class or visit the corresponding PR.
Note: this generator is on its experimental stage and any feedback is very welcomed.
Before 1.2.0, it was impossible to register context serializer for generic class, because contextual function accepted a single serializer. Now it is possible to register a provider — lambda that allows to construct a serializer for generic class out of its type arguments serializers. See the details in the documentation.
This release contains all features and bugfixes from 1.1.0-RC plus an additional fix for incorrect exception type (#1325 — Throw SerializationException instead of IllegalStateException in EnumSerializer) and uses release version of Kotlin 1.4.30.
In the light of JCenter shutdown, starting from 1.1.0-RC and now on, all new releases of kotlinx.serialization are published directly to Maven Central and therefore are not available in https://kotlin.bintray.com/kotlinx/ repository. We suggest you to remove jcenter() and other kotlin bintray repositories from your buildscripts and to use mavenCentral() repository instead.
This is a release candidate of 1.1.0 version. Note that final 1.1.0 version may include more features and bugfixes, which would be listed in the corresponding changelog.
Due to changes in calling conventions between compiler plugin and serialization core runtime, this release requires Kotlin version at least 1.4.30-M1. However, this changes should not affect your code, because only deprecated functions were removed from public API. See corresponding PR for the details.
Using 1.1.0-RC, you can mark inline classes as @Serializable and use them in other serializable classes. Unsigned integer types (UByte, UShort, UInt and ULong) are serializable as well and have special support in JSON. This feature requires Kotlin compiler 1.4.30-RC and enabling new IR compilers for JS and JVM.
You can learn more in the documentation and corresponding pull request.
serializerOrNull function for KType and Type arguments (#1164)Properties (#1183) (thanks to TorRanfelt)Properties values as Strings (#1158) (thanks to daniel-jasinski)JsonElement deserialization (#1300)SerializationException instead of ISE when encountering an invalid boolean in JSON (#1299)ProtoBuf (#1294)MissingFieldException message (#1153)@UseSerializers annotation (#1195)JsonObject.toString() (#1246) (thanks to Karlatemp)Collection as ArrayList in serializer by type lookups (#1257)This patch release contains several feature improvements as well as bugfixes and performance improvements.
dynamic conversions on JS platform (#1122)The first public stable release, yay! The definitions of stability and backwards compatibility guarantees are located in the corresponding document. We now also have a GitHub Pages site with full API reference.
Compared to RC2, no new features apart from #947 were added and all previously deprecated declarations and migrations were deleted. If you are using RC/RC2 along with deprecated declarations, please, migrate before updating to 1.0.0. In case you are using pre-1.0 versions (e.g. 0.20.0), please refer to our migration guide.
encodeDefaults (#1108) (thanks to Anders Carling)Second release candidate for 1.0.0 version. This RC contains tweaks and changes based on users feedback after 1.0.0-RC.
In 1.0.0-RC, the kotlinx-serialization-core artifact contained core serialization entities as well as Json serial format. We've decided to change that and to make core format-agnostic. It would make the life easier for those who use other serial formats and also make possible to write your own implementation of JSON or another format without unnecessary dependency on the default one.
In 1.0.0-RC2, Json class and related entities are located in kotlinx-serialization-json artifact. To migrate, simply replace kotlinx-serialization-core dependency with -json. Core library then will be included automatically as the transitive dependency.
For most use-cases, you should use new kotlinx-serialization-json artifact. Use kotlinx-serialization-core if you are writing a library that depends on kotlinx.serialization in a format-agnostic way of provides its own serial format.
encodeDefaults flag is now set to false in the default configuration for JSON, CBOR and Protocol Buffers.The change is motivated by the fact that in most real-life scenarios, this flag is set to false anyway, because such configuration reduces visual clutter and saves amount of data being serialized. Other libraries, like GSON and Moshi, also have this behavior by default.
This may change how your serialized data looks like, if you have not set value for encodeDefaults flag explicitly. We anticipate that most users already had done this, so no migration is required. In case you need to return to the old behavior, simply add encodeDefaults = true to your configuration while creating Json/Cbor/ProtoBuf object.
Json.encodeToDynamic/Json.decodeFromDynamic functions to json packageSince these functions are no longer exposed via DynamicObjectParser/Serializer and they are now Json class extensions, they should be moved to kotlinx.serialization.json package. To migrate, simply add import kotlinx.serialization.json.* to your files.
dynamic encoding/decoding (#1080)dynamic encoding/decodingRelease candidate for 1.0.0 version. The goal of RC release is to collect feedback from users and provide 1.0.0 release with bug fixes and improvements based on that feedback.
While working on 1.0.0 version, we carefully examined every public API declaration of the library and split it to stable API, that we promise to be source and binary-compatible, and experimental API, that may be changed in the future. Experimental API is annotated with @ExperimentalSerializationApi annotation, which requires opt-in. For a more detailed description of the guarantees, please refer to the compatibility guide.
The id of the core artifact with @Serializable annotation and Json format was changed from kotlinx-serialization-runtime to kotlinx-serialization-core to be more clear and aligned with other kotlinx libraries.
A significant part of the public API was renamed or extracted to a separate package. To migrate from the previous versions of the library, please refer to the migration guide.
Core API changes
stringify and parse are renamed to encodeToString and decodeFromStringparseJson and fromJson are renamed to parseToJsonElement and decodeFromJsonElementJson constructor is replaced with Json {} builder function, JsonConfiguration is deprecated in favor of Json {} builder
Json implementations are removedJson companion object extends JsonJson configuration
prettyPrintIndent allows only whitespacesserializeSpecialFloatingPointValues is renamed to allowSpecialFloatingPointValues. It now affects both serialization and deserialization behaviourunquoted JSON flag is deprecated for removalcoerceInputValues option for null-defaults and unknown enums (#90, #246)Simplification of JsonElement API
JsonElement API are deprecated or extracted to extensionsJsonLiteral is deprecated in favor of JsonPrimitive constructors with nullable parameterJsonElement builders rework to be aligned with stdlib collection builders (#418, #627)
to and unaryPlus in JSON DSL in favor of put/add functionsjsonObject {} and json {} builders are renamed to buildJsonObject {} and buildJsonArray {}inline (#703)JavaScript support
DynamicObjectParser is deprecated in the favor of Json.decodeFromDynamic extension functionsJson.encodeToDynamic extension is added as a counterpart to Json.decodeFromDynamic (former DynamicObjectParser) (#116)Other API changes:
JsonInput and JsonOutput are renamed to JsonDecoder and JsonEncoderJsonTransformingSerializer are renamed to transformSerialize and transformDeserializeJsonParametricSerializer is renamed to JsonContentPolymorphicSerializerJsonEncodingException and JsonDecodingException are made internalBug fixes
IllegalStateException when null occurs in JSON input in the place of an expected non-null object (#816)The new naming scheme for SerialFormats
StringFormat and BinaryFormat are renamed and now follow the same naming schemestringify/parse are renamed to encodeToString/decodeFromStringencodeToByteArray/encodeToHexString/decodeFromByteArray/decodeFromHexString in BinaryFormat are introduced instead of dump/dumps/load/loadsNew format instances building convention
SerialDescriptor-related API
SerialDescriptor and SerialKind are moved to a separate kotlinx.serialization.descriptors packageENUM and CONTEXTUAL kinds now extend SerialKind directlyPrimitiveDescriptor is renamed to PrimitiveSerialDescriptorbuildClassSerialDescriptor to use with classes' custom serializers, creating other kinds is considered experimental for nowelementDescriptors) with properties that return iterable as an optimizationIndexOutOfBoundsException in descriptor.getElementDescriptor(index) for List after upgrade to 0.20.0 is fixed (#739)SerializersModule-related API
SerialModule is renamed to SerializersModuleSerialModuleCollector is renamed to SerializersModuleCollectorSerializersModule {} DSL)with in polymorphic builder in favor of subclass()polymorphicDefault API for cases when type discriminator is not registered or absent (#902)Contextual serialization
@ContextualSerialization is split into two annotations: @Contextual to use on properties and @UseContextualSerialization to use on fileSerialDescriptor.capturedKClass API to introspect SerializersModule-based contextual and polymorphic kinds (#515, #595)Encoding-related API
Encoder, Decoder, AbstractEncoder, AbstractDecoder) are moved to a separate kotlinx.serialization.encoding packagetypeParameters argument in beginStructure/beginCollection methodsupdateSerializableValue and similar methods and UpdateMode enumREAD_DONE to DECODE_DONEinline where applicablekotlinx.io mockery (InputStream, ByteArrayInput, etc) is removedSerializer-related API
UnitSerializer is replaced with Unit.serializer()serializerserializer by KType/Java's Reflect Type functions (#902, #903)SerializationException.@ImplicitReflectionSerializer is deprecatedProtoBuf constructor is replaced with ProtoBuf {} builder functionProtoBuf companion object now extends ProtoBufProtoId is renamed to ProtoNumber, ProtoNumberType to ProtoIntegerType to be consistent with ProtoBuf specificationSerializationException is thrown instead of IllegalStateException on incorrect input (#870)ProtobufDecodingException is made internalConfigParser is renamed to Hocon, kotlinx-serialization-runtime-configparser artifact is renamed to kotlinx-serialization-hocon0.20.0 release is focused on giving a library its final and stable API shape.
We have carefully evaluated every public declaration and decided whether it should be publicly available. As a result, some declarations were deprecated with an intention of removing them from public API because they are going to be replaced with others, more valuable and useful for users.
Deprecated symbols include:
nonStrict — strictMode was split to 3 separate, more granular, flags. Users are encouraged to create their own configuration;IntSerializer and ArrayListSerializer. They were replaced with constructor-like factory functions.SerialClassDescImpl creation class replaced with SerialDescriptor builder function to ease writing of custom serializers and maintain SerialDescriptor contract.We have spent a lot of effort into the quality, documenting most of the core interfaces, establishing their contracts, fixing numerous of bugs, and even introducing new features that may be useful for those of you who write custom serializers — see JsonTransformingSerializer.
Such API changes, of course, may be not backwards-compatible in some places, in particular, between compiler plugin and runtime. Given that the library is still is in the experimental phase, we took the liberty to introduce breaking changes in order to give users the better, more convenient API. Therefore, this release has number 0.20.0 instead of 0.15.0; Kotlin 1.3.70 is compatible only with this release.
To migrate:
Replace import kotlinx.serialization.internal.* with import kotlinx.serialization.builtins.*. This action is sufficient for most of the cases, except primitive serializers — instead of using IntSerializer, use Int.serializer(). For other object-like declarations, you may need to transform it to function call: ByteArraySerializer => ByteArraySerializer().
Pay attention to the changed JsonConfiguration constructor arguments: instead of strictMode, now three different flags are available: ignoreUnknownKeys, isLenient, and serializeSpecialFloatingPointValues.
If you used formats other than JSON, make sure you've included the corresponding artifact as dependency, because now they're located outside of core module. See formats list for particular artifact coordinates.
Other corresponding deprecation replacements are available via standard @Deprecated(replaceWith=..) mechanism. (use Alt+Enter for quickfix replacing).
ProtoBuf.shouldEncodeElementDefault to false (#397, #71)serializer() function in companion for generic classes because user can define a parameterless shorthand one (#228)equals, hashCode of JsonObject and JsonArray..simpleName was not available for primitives' KClasses.jsonparser artifact)Not working until plugin is updated:
Not working until plugin is updated:
Not working until plugin is updated:
Not working until plugin is updated:
equals on collections' descriptorsisElementOptionalMapper.readNotNullMark, because tag can be only prefix for nested object. Fixes #182Plugin:
Runtime:
Plugin:
@Serializable(with) on properties on JS too.Runtime: