Changelog History
Page 1
-
v1.4.1 Changes
October 14, 2022π This is patch release contains several bugfixes and improvements. 0οΈβ£ 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 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)
-
v1.4.0 Changes
August 18, 2022π This release contains all features and bugfixes from 1.4.0-RC plus some bugfixes on its own (see below). 0οΈβ£ Kotlin 1.7.10 is used as a default.
π Bugfixes
- Fixed decoding of huge JSON data for okio streams (#2006)
-
v1.4.0-RC Changes
July 20, 2022π This is a candidate for the next big release with many new exciting features to try. 0οΈβ£ It uses Kotlin 1.7.10 by default.
Integration with Okio's BufferedSource and BufferedSink
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 calledJson.decodeFromBufferedSource
andJson.encodeToBufferedSink
, respectively. There's alsodecodeBufferedSourceToSequence
that behaves similarly todecodeToSequence
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 idkotlinx-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 numbers do not require experimental annotations anymore
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, π namelySerialDescriptor.isInline
,Encoder.encodeInline
, and some others. We've also updated related [documentation article](docs/value-classes.md).β Additionally, all
@ExperimentalUnsignedTypes
annotations were removed completely, so you can freely use types such asUInt
and their respective serializers as a stable feature without opt-in requirement.Part of SerializationException's hierarchy is public now
π 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 makingMissingFieldException
public. π One can use it in thecatch
clause to better understand the reasons of failure β for example, to return 400 instead of 500 from an HTTP server β π and then use itsfields
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 throwIllegalStateException
to indicate problems unrelated to serialization, such as data validation in classes' constructors.@MetaSerializable annotation
π 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.
π Moving documentation from GitHub pages to kotlinlang.org
π 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.Other improvements
- Allow Kotlin's null literal in JSON DSL (#1907) (thanks to Lukellmann)
- Stabilize EmptySerializersModule (#1921)
- Boost performance of polymorphic deserialization in optimistic scenario (#1919)
- Added serializer for the
kotlin.time.Duration
class (plugin support comes in Kotlin 1.7.20) (#1960) - Support tagged not null marks in TaggedEncoder/Decoder (#1954) (thanks to EdwarDDay)
π Bugfixes
- Support quoting unsigned integers when used as map keys (#1969)
- Fix protocol buffer enum schema generation (#1967) (thanks to mogud)
- Support diamond inheritance of sealed interfaces in SealedClassSerializer (#1958)
- Support retrieving serializer for sealed interface (#1968)
- Fix misleading token description in JSON errors (#1941) (thanks to TheMrMilchmann)
-
v1.3.3 Changes
May 11, 2022π This release contains support for Protocol Buffers packed fields, as well as several bugfixes. 0οΈβ£ It uses Kotlin 1.6.21 by default.
Protobuf packed fields
π 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 onlyList
and primitive collection such asIntArray
types. 0οΈβ£ 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!
Other improvements & small features
- Incorporate JsonPath into exception messages (#1841)
- Mark block in corresponding encodeStructure/decodeStructure extensions as crossinline to reduce amount of bytecode (#1917)
- Support serialization of compile-time
Collection<E>
properties that are not lists at the runtime (#1821) - Best-effort kotlin reflect avoidance in serializer(Type) (#1819)
π Bugfixes
- Iterate over element indices in ObjectSerializer in order to let the format skip unknown keys (#1916)
- Correctly support registering both default polymorphic serializer & deserializer (#1849)
- Make error message for captured generic type parameters much more straightforward (#1863)
-
v1.3.2 Changes
December 23, 2021π This release contains several features and bugfixes for core API as well as for HOCON format. 0οΈβ£ It uses Kotlin 1.6.10 by default.
Serializing objects to HOCON
It's now possible to encode Kotlin objects to
Config
values with newHocon.encodeToConfig
function. This feature may help edit existing configs inside Kotlin program or generate new ones.Big thanks to Osip Fatkullin for implementing this.
0οΈβ£ Polymorphic default serializers
π As of now,
polymorphicDefault
clause insideSerializersModule { }
builder specifies a fallback serializer to be used only during deserialization process. A new function has been introduced to allow setting 0οΈβ£ fallback serializer for serialization:polymorphicDefaultSerializer
. This function should ease serializing vast hierarchies of third-party or Java classes.0οΈβ£ Note that there are two new experimental functions,
polymorphicDefaultSerializer
andpolymorphicDefaultDeserializer
. π To avoid naming confusion, we are going to deprecatepolymorphicDefault
in favor ofpolymorphicDefaultDeserializer
in the next minor release (1.4.0).π» Credit for the PR goes to our contributor Joseph Burton.
Other improvements
- HOCON: parse strings into integers and booleans if possible (#1795) (thanks to tobiaslieber)
- Add an encodeCollection extensions (#1749) (thanks to Nicklas Ansman Giertz)
π Bugfixes
- Properly handle top-level value classes in encodeToJsonElement (#1777)
- Fix incorrect handling of object end when JsonTreeReader (JsonElement) is used with decodeToSequence (#1782)
-
v1.3.1 Changes
November 11, 2021π This release mainly contains bugfixes for 1.3.0 and provides new experimental
Json.decodeToSequence
function.π Improvements
- Provide decodeToSequence to read multiple objects from stream lazily (#1691)
π Bugfixes
- Correctly handle buffer boundaries while decoding escape sequences from json stream (#1706)
- Properly skip unknown keys for objects and structures with zero properties (#1720)
- Fix merging for maplikeSerializer when the map is not empty (by using the actual size * 2). (#1712) (thanks to pdvrieze)
- Fix lookup of primitive array serializers by Java type token (#1708)
-
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
andJson.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 theencodeDefaults
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 whethernull
property values should be included in the serialized JSON string. 0οΈβ£ The difference fromencodeDefaults
is thatexplicitNulls = false
flag drops null values even if the property does not have a default value. 0οΈβ£ Upon deserializing such a missing property, anull
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/json.md#explicit-nulls) 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 asjlink
and various technologies such asTorandoFX
.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
, andtvosSimulatorArm64
.π 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)
- 0οΈβ£
-
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
andcoerceInputValues
inJson.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 ofClassCastException
during unexpected null inTreeJsonDecoder
(#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)
- Support for
-
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)