All Versions
Latest Version
Avg Release Cycle
48 days
Latest Release
27 days ago

Changelog History
Page 1

  • v1.3.0 Changes

    September 23, 2021

    πŸš€ This release contains all of the cool new features from 1.3.0-RC (see below) as well as minor improvements. 0️⃣ It uses Kotlin 1.5.31 by default.

    πŸ›  Bugfixes and improvements

    • Promote JsonConfiguration and its usages to stable (#1690)
    • Remove opt-in annotations from SerialFormat, StringFormat, BinaryFormat (#1688)
    • Correctly throw SerializationException instead of IOOBE for some cases with EOF in streams (#1677)
    • CBOR: ignore tags when reading (#1614) (thanks to David Robertson)
  • v1.3.0-RC Changes

    September 06, 2021

    πŸš€ 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. 0️⃣ Kotlin 1.5.30 is used by default.

    Java IO stream-based JSON serialization

    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.

    0️⃣ Property-level control over defaults values encoding

    0️⃣ 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 }. 0️⃣ In 1.3.0 we’re extending this feature by adding a new way to fine-tune the serialization of default values: 0️⃣ you can now control it on the property level using the new @EncodeDefaults annotation.

    0️⃣ @EncodeDefaults annotation has a higher priority over the encodeDefaults property and takes one of two possible values:

    • 0️⃣ 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.

    0️⃣ 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.

    Excluding null values from JSON serialization

    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. 0️⃣ The difference from encodeDefaults is that explicitNulls = false flag drops null values even if the property does not have a default value. 0️⃣ Upon deserializing such a missing property, a null or default value (if it exists) will be used.

    0️⃣ To maintain backwards compatibility, this flag is set to true by default. πŸ“š You can learn more in the [documentation](docs/ or the PR.

    Per-hierarchy polymorphic class discriminators

    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.

    πŸ‘Œ Support for Java module system

    πŸš€ 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.

    Native targets for Apple Silicon

    πŸš€ This release includes klibs for new targets, introduced in Kotlin/Native 1.5.30 β€” 🍎 macosArm64, iosSimulatorArm64, watchosSimulatorArm64, and tvosSimulatorArm64.

    πŸ›  Bugfixes and improvements

    • Properly handle quoted 'null' literals in lenient mode (#1637)
    • Switch on deep recursive function when nested level of JSON is too deep (#1596)
    • Support for local serializable classes in IR compiler
    • Support default values for @SerialInfo annotations in IR compiler
    • Improve error message for JsonTreeReader (#1597)
    • Add guide for delegating serializers and wrapping serial descriptor (#1591)
    • Set target JVM version to 8 for Hocon module in Gradle metadata (#1661)
  • v1.2.2 Changes

    July 08, 2021

    πŸ›  This release contains various bugfixes, some useful features and important performance improvements. 0️⃣ It also uses Kotlin 1.5.20 as default.

    πŸ”‹ Features

    • Support for @JsonNames and coerceInputValues in Json.decodeFromDynamic (#1479)
    • Add factory function to wrap a serial descriptor with a custom name for custom delegating serializers (#1547) (thanks to Fadenfire)
    • Allow contextually serialized types to be used as map keys in Json (#1552) (thanks to pdvrieze)

    πŸ›  Bugfixes and performance improvements

    • Update size in JsonStringBuilder slow-path to avoid excessive array-copies for large strings with escape symbols (#1491)
    • Optimize integer encoding length in CBOR (#1570) (thanks to davertay)
    • Throw JsonDecodingException instead of ClassCastException during unexpected null in TreeJsonDecoder (#1550)
    • Prohibit 'null' strings in lenient mode in order to get rid of 'null' and "null" ambiguity (#1549)
    • Avoid usage of reflective-like serialDescriptor<KType> in production sources (#1540)
    • Added correct error message when deserializing missing enum member for Properties format (#1539)
    • Make DescriptorSchemaCache in Json thread-local on Native (#1484)
  • v1.2.1 Changes

    May 14, 2021

    πŸ›  This release mainly contains bugfixes for various issues, including important broken thread-safety and improper encoding.

    πŸ”‹ Features

    • Added support for nullable values, nested and empty collections in protobuf (#1430)

    πŸ›  Bugfixes

    • Support @JsonNames for enum values (#1473)
    • Handle EOF in skipElement correctly (#1475)
    • Allow using value classes with primitive carriers as map keys (#1470)
    • Read JsonNull only for non-string literals in JsonTreeReader (#1466)
    • Properly reuse JsonStringBuilders in CharArrayPool (#1455)
    • Properly ensure capacity of the string builder on the append slow-path (#1441)
  • v1.2.0 Changes

    April 27, 2021

    πŸš‘ 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; 0️⃣ Kotlin 1.5.0 is used as a default compiler and language version.

    🐎 JSON performance improvements

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

    Ability to specify alternative names during JSON decoding

    πŸ›  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 in public API

    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.

    Generator for .proto files based on serializable Kotlin classes

    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.

    Contextual serialization of generic classes

    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.

    Other features

    • Support for watchosX64 target (#1366).
    • Introduce kotlinx-serialization-bom (#1356).
    • Support serializer on JS IR when T is an interface (#1431).

    πŸ›  Bugfixes

    • Fix serializer lookup by KType for third party classes (#1397) (thanks to mvdbos).
    • Fix inability to encode/decode inline class with string to JsonElement (#1408).
    • Throw SerializationException instead of AIOB in ProtoBuf (#1373).
    • Fix numeric overflow in JsonLexer (#1367) (thanks to EdwarDDay).
  • v1.1.0 Changes

    February 17, 2021

    πŸ›  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 repository. πŸ— We suggest you to remove jcenter() and other kotlin bintray repositories from your buildscripts and to use mavenCentral() repository instead.

  • v1.1.0-RC Changes

    February 03, 2021

    πŸ›  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.

    ⚑️ Kotlin version requirement updated

    πŸš€ 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.

    πŸ‘ Experimental support for inline classes (IR only)

    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](docs/ and corresponding pull request.

    Other features

    • Add serializerOrNull function for KType and Type arguments (#1164)
    • Allow shared prefix names in Properties (#1183) (thanks to TorRanfelt)
    • Add support for encoding/decoding Properties values as Strings (#1158) (thanks to daniel-jasinski)

    πŸ›  Bugfixes and performance improvements

    • Support contextual serialization for derived classes (#1277) (thanks to Martin Raison)
    • Ensure serialization is usable from K/N background thread (#1282)
    • Fail on primitive type overflow during JsonElement deserialization (#1300)
    • Throw SerializationException instead of ISE when encountering an invalid boolean in JSON (#1299)
    • Optimize the loop for writing large varints in ProtoBuf (#1294)
    • Fix serializing property with custom accessors and backing field (#1197)
    • Optimize check for missing fields in deserialization and improve MissingFieldException message (#1153)
    • Improved support of nullable serializer in @UseSerializers annotation (#1195)
    • Correctly escape keys in JsonObject.toString() (#1246) (thanks to Karlatemp)
    • Treat Collection as ArrayList in serializer by type lookups (#1257)
    • Do not try to end structure in encode/decode structure extensions if an exception has been thrown, so the original exception will be propagated (#1201)
    • Properly cache serial names in order to improve performance of JSON parser with strict mode (#1209)
    • Fix dynamic serialization for nullable values (#1199) (thanks to ankushg)
  • v1.0.1 Changes

    October 28, 2020

    πŸ›  This patch release contains several feature improvements as well as bugfixes and performance improvements.

    πŸ”‹ Features

    • βž• Add object-based serialization and deserialization of polymorphic types for dynamic conversions on JS platform (#1122)
    • βž• Add support for object polymorphism in HOCON decoder (#1136)
    • βž• Add support of decoding map in the root of HOCON config (#1106)

    πŸ›  Bugfixes

    • πŸ”Œ Properly cache generated serializers in PluginGeneratedSerialDescriptor (#1159)
    • βž• Add Pair and Triple to serializer resolving from Java type token (#1160)
    • πŸ›  Fix deserialization of half-precision, float and double types in CBOR (#1112)
    • πŸ›  Fix ByteString annotation detection when ByteArray is nullable (#1139) (thanks to Travis Wyatt)
  • v1.0.0 Changes

    October 08, 2020

    πŸš€ 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.

    πŸ›  Bugfixes and improvements

    • πŸ‘Œ Support nullable types at top-level for JsonElement decoding (#1117)
    • βž• Add CBOR ignoreUnknownKeys option (#947) (thanks to Travis Wyatt)
    • πŸ›  Fix incorrect documentation of encodeDefaults (#1108) (thanks to Anders Carling)
  • v1.0.0-RC2 Changes

    September 21, 2020

    πŸš€ Second release candidate for 1.0.0 version. This RC contains tweaks and changes based on users feedback after 1.0.0-RC.

    Major changes

    JSON format is now located in different artifact (#994)

    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
    0️⃣ 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.
    0️⃣ Other libraries, like GSON and Moshi, also have this behavior by default.

    0️⃣ 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.

    πŸ“¦ Move Json.encodeToDynamic/Json.decodeFromDynamic functions to json package

    πŸ“œ Since 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.

    πŸ›  Bugfixes and improvements

    • 0️⃣ Do not provide default implementation for serializersModule in AbstractEncoder/Decoder (#1089)
    • πŸ‘Œ Support JsonElement hierarchy in dynamic encoding/decoding (#1080)
    • πŸ‘Œ Support top-level primitives and primitive map keys in dynamic encoding/decoding
    • πŸ”„ Change core annotations retention (#1083)
    • πŸ›  Fix 'Duplicate class ... found in modules' on Gradle != 6.1.1 (#996)
    • πŸ“š Various documentation clarifications
    • πŸ‘Œ Support deserialization of top-level nullable types (#1038)
    • πŸ‘» Make most serialization exceptions eligible for coroutines exception recovery (#1054)
    • Get rid of methods that do not present in Android API<24 (#1013, #1040)
    • Throw JsonDecodingException on empty string literal at the end of the input (#1011)
    • βœ‚ Remove new lines in deprecation warnings that caused errors in ObjC interop (#990)