Changelog History
Page 2
-
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 ofJson
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 newProtoBufSchemaGenerator
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
-
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 ofIllegalStateException
inEnumSerializer
) 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 removejcenter()
and other kotlin bintray repositories from your buildscripts and to usemavenCentral()
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
andULong
) 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/inline-classes.md) and corresponding pull request.
Other features
- Add
serializerOrNull
function forKType
andType
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
asArrayList
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)
- Add
-
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)
- โ Add object-based serialization and deserialization of polymorphic types for
-
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 asJson
serial format.
We've decided to change that and to makecore
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 inkotlinx-serialization-json
artifact.
To migrate, simply replacekotlinx-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. Usekotlinx-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 tofalse
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 addencodeDefaults = true
to your configuration while creatingJson/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 nowJson
class extensions,
๐ฆ they should be moved tokotlinx.serialization.json
package.
To migrate, simply addimport 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)
-
v1.0.0-RC Changes
August 17, 2020๐ Release 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 andJson
format was changed
fromkotlinx-serialization-runtime
tokotlinx-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.API changes
Json
Core API changes
stringify
andparse
are renamed toencodeToString
anddecodeFromString
parseJson
andfromJson
are renamed toparseToJsonElement
anddecodeFromJsonElement
- Reified versions of methods are extracted to extensions
๐
Json
constructor is replaced withJson {}
builder function,JsonConfiguration
is deprecated in favor
๐ ofJson {}
builder- All default
Json
implementations are removed
-
Json
companion object extendsJson
๐ง Json configuration
prettyPrintIndent
allows only whitespacesserializeSpecialFloatingPointValues
is renamed toallowSpecialFloatingPointValues
. It now affects both serialization and deserialization behaviourunquoted
JSON flag is deprecated for removal
- New
coerceInputValues
option for null-defaults and unknown enums (#90, #246)Simplification of
JsonElement
API- Redundant members of
JsonElement
API are deprecated or extracted to extensions - Potential error-prone API is removed
-
JsonLiteral
is deprecated in favor ofJsonPrimitive
constructors with nullable parameter๐
JsonElement
builders rework to be aligned with stdlib collection builders (#418, #627)- Deprecated infix
to
and unaryPlus in JSON DSL in favor ofput
/add
functions jsonObject {}
andjson {}
builders are renamed tobuildJsonObject {}
andbuildJsonArray {}
- Make all builders
inline
(#703)๐ JavaScript support
DynamicObjectParser
is deprecated in the favor ofJson.decodeFromDynamic
extension functions
-
Json.encodeToDynamic
extension is added as a counterpart toJson.decodeFromDynamic
(formerDynamicObjectParser
) (#116)Other API changes:
JsonInput
andJsonOutput
are renamed toJsonDecoder
andJsonEncoder
- Methods in
JsonTransformingSerializer
are renamed totransformSerialize
andtransformDeserialize
JsonParametricSerializer
is renamed toJsonContentPolymorphicSerializer
-
JsonEncodingException
andJsonDecodingException
are made internal๐ Bug fixes
IllegalStateException
whennull
occurs in JSON input in the place of an expected non-null object (#816)- java.util.NoSuchElementException when deserializing twice from the same JsonElement (#807)
Core API for format authoring
The new naming scheme for
SerialFormats
- Core functions in
StringFormat
andBinaryFormat
are renamed and now follow the same naming scheme stringify
/parse
are renamed toencodeToString
/decodeFromString
-
encodeToByteArray
/encodeToHexString
/decodeFromByteArray
/decodeFromHexString
inBinaryFormat
are introduced instead ofdump
/dumps
/load
/loads
๐ New format instances building convention
- Constructors replaced with builder-function with the same name to have the ability to add new configuration parameters,
while preserving both source and binary compatibility
- Format's companion objects now extend format class and can be used interchangeably
SerialDescriptor-related API
SerialDescriptor
andSerialKind
are moved to a separatekotlinx.serialization.descriptors
packageENUM
andCONTEXTUAL
kinds now extendSerialKind
directlyPrimitiveDescriptor
is renamed toPrimitiveSerialDescriptor
- Provide specific
buildClassSerialDescriptor
to use with classes' custom serializers, creating other kinds is considered experimental for now - Replace extensions that returned lists (e.g.
elementDescriptors
) with properties that return iterable as an optimization
-
IndexOutOfBoundsException
indescriptor.getElementDescriptor(index)
forList
after upgrade to 0.20.0 is fixed (#739)SerializersModule-related API
SerialModule
is renamed toSerializersModule
SerialModuleCollector
is renamed toSerializersModuleCollector
- All builders renamed to be aligned with a single naming scheme (e.g.
SerializersModule {}
DSL) - Deprecate infix
with
in polymorphic builder in favor of subclass() - Helper-like API is extracted to extension functions where possible.
-
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 file
- New
SerialDescriptor.capturedKClass
API to introspect SerializersModule-based contextual and polymorphic kinds (#515, #595)Encoding-related API
- Encoding-related classes (
Encoder
,Decoder
,AbstractEncoder
,AbstractDecoder
) are moved to a separatekotlinx.serialization.encoding
package - Deprecated
typeParameters
argument inbeginStructure
/beginCollectio
n methods - Deprecated
updateSerializableValue
and similar methods andUpdateMode
enum - Renamed
READ_DONE
toDECODE_DONE
- Make extensions
inline
where applicable
-
kotlinx.io
mockery (InputStream
,ByteArrayInput
, etc) is removedSerializer-related API
UnitSerializer
is replaced withUnit.serializer()
- All methods for serializers retrieval are renamed to
serializer
- Context is used as a fallback in
serializer
by KType/Java's Reflect Type functions (#902, #903) - Deprecated all exceptions except
SerializationException
. @ImplicitReflectionSerializer
is deprecated- Support of custom serializers for nullable types is added (#824)
ProtoBuf
- ๐
ProtoBuf
constructor is replaced withProtoBuf {}
builder function ProtoBuf
companion object now extendsProtoBuf
ProtoId
is renamed toProtoNumber
,ProtoNumberType
toProtoIntegerType
to be consistent with ProtoBuf specification- ๐ ProtoBuf performance is significantly (from 2 to 10 times) improved (#216)
- ๐ Top-level primitives, classes and objects are supported in ProtoBuf as length-prefixed tagless messages (#93)
SerializationException
is thrown instead ofIllegalStateException
on incorrect input (#870)ProtobufDecodingException
is made internal
Other formats
- ๐ All format constructors are migrated to builder scheme
- Properties serialize and deserialize enums as strings (#818)
- ๐ CBOR major type 2 (byte string) support (#842)
- ๐
ConfigParser
is renamed toHocon
,kotlinx-serialization-runtime-configparser
artifact is renamed tokotlinx-serialization-hocon
- Do not write/read size of collection into Properties' map (#743)
-
v0.20.0 Changes
March 04, 2020๐ Release notes
๐ 0.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:
- Pre-defined JSON instances like
nonStrict
โstrictMode
was split to 3 separate, more granular, flags. ๐ง Users are encouraged to create their own configuration; - Top-level serializers like
IntSerializer
andArrayListSerializer
. They were replaced with constructor-like factory functions. SerialClassDescImpl
creation class replaced withSerialDescriptor
๐ builder function to ease writing of custom serializers and maintainSerialDescriptor
contract.- Internal utilities, like HexConverter and ByteBuffer, were deprecated as not relevant to serialization public API.
- Add-on formats like Protobuf, CBOR and Properties (formerly Mapper) are now extracted to [separate artifacts](formats/README.md#protobuf) to keep the core API lightweight.
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](docs/json_transformations.md).
๐ 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 of0.15.0
; Kotlin 1.3.70 is compatible only with this release.To migrate:
Replace
import kotlinx.serialization.internal.*
withimport kotlinx.serialization.builtins.*
. This action is sufficient for most of the cases, except primitive serializers โ instead of usingIntSerializer
, useInt.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 ofstrictMode
, now three different flags are available:ignoreUnknownKeys
,isLenient
, andserializeSpecialFloatingPointValues
.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](formats/README.md) for particular artifact coordinates.
๐ 4. Other corresponding deprecation replacements are available via standard
@Deprecated(replaceWith=..)
mechanism. (use Alt+Enter for quickfix replacing).Full changelog (by commit):
- This release is compatible with Kotlin 1.3.70
- Rework polymorphic descriptors: polymorphic and sealed descriptor elements are now aligned with an actual serialization process (#731)
- Hide internal collection and map serializers
- Introduce factories for ArraySerializers as well, deprecate top-level array serializers
- Extract ElementValue encoder and decoder to builtins and rename it to AbstractEncoder and AbstractDecoder respectively
- Hide as much internal API as possible for collections. Now ListSerializer(), etc factories should be used
- Replace top-level primitive serializers with corresponding companion functions from builtins
- Move Tagged.kt to internal package
- Hide tuple serializers from the public usages and replace them with factory methods in builtins package
- Deprecate top-level format instances, leave only companion objects
- Document contracts for JsonInput/JsonOutput (#715)
- Ensure that serialization exception is thrown from JSON parser on invalid inputs (#704)
- Do best-effort input/output attach to exceptions to simplify debugging
- JSON configuration rework: strictMode is splitted into three flags.
- Make strictMode even more restrictive, prohibit unquoted keys and values by default, always use strict boolean parser (#498, #467)
- Preserve quotation information during JsonLiteral parsing (#536, #537)
- Change MapEntrySerializer.descriptor to be truly map-like. Otherwise, it cannot be properly serialized by TaggedDecoder (-> to JsonObject)
- Cleanup ConfigParser: move to proper package to be consistent with other formats
- Support primitive and reference arrays in serializer(KType)
- Add option to use HOCON naming convention
- Allow DynamicObjectParser to handle polymorphic types (array-mode polymorphism only)
- Get rid of PrimitiveKind.UNIT and corresponding encoder methods. Now UNIT encoded as regular object.
- JsonParametricSerializer and JsonTransformingSerializer implementation
- Remove AbstractSerialFormat superclass since it is useless
- Deprecate most of the functions intended for internal use
- Document core kotlinx.serialization.* package
- Introduce UnionKind.CONTEXTUAL to cover Polymorphic/Contextual serializers, get rid of elementsCount in builders
- SerialDescriptor for enums rework: now each enum member has object kind
- Introduce DSL for creating user-defined serial descriptors
- Update README with Gradle Kotlin DSL (#638)
- Fix infinite recursion in EnumDescriptor.hashCode() (#666)
- Allow duplicating serializers during SerialModule concatenation if they are equal (#616)
- Rework sealed class discriminator check to reduce the footprint of the check when no JSON is used
- Detect collisions with class discriminator and for equal serial names within the same sealed class hierarchy (#457)
- Detect name conflicts in polymorphic serialization during setup phase (#461, #457, #589)
- Extract all mutable state in modules package to SerialModuleBuilder to have a single mutable point and to ensure that SerialModule can never be modified
- Omit nulls in Properties.store instead of throwing an exception
- Add optionals handling to Properties reader (#460, #79)
- Support StructureKind.MAP in Properties correctly (#406)
- Move Mapper to separate 'properties' module and rename it to Properties
- Reified extensions for registering serializers in SerialModule (#671, #669)
- Promote KSerializer.nullable to public API
- Object serializer support in KType and Type based serializer lookups on JVM (#656)
- Deprecate HexConverter
- Supply correct child descriptors for Pair and Triple
- Rename SerialId to ProtoId to better reflect its semantics
- Support of custom generic classes in typeOf()/serializer() API (except JS)
- Allow setting
ProtoBuf.shouldEncodeElementDefault
to false (#397, #71) - Add Linux ARM 32 and 64 bit targets
- Reduce number of internal dependencies: deprecate IOException, mark IS/OS as internal serialization API (so it can be removed in the future release)
- Reduce number of internal dependencies and use bitwise operations in ProtoBuf/Cbor instead of ByteBuffer. Deprecate ByteBuffer for removal
- Extract ProtoBuf & CBOR format to the separate module
- READ_ALL rework (#600)
- SerialDescriptor API standartization (#626, #361, #410)
- Support polymorphism in CBOR correctly (fixes #620)
- Add forgotten during migration WASM32 target (#625)
- Fix exception messages & typos in JsonElement (#621)
- Pre-defined JSON instances like
-
v0.14.0 Changes
November 19, 2019- Bump version to 0.14.0 @ Kotlin 1.3.60
- Add empty javadoc artifact to linking with Maven Central
- Mark more things as @InternalSerializationApi.
- Support @SerialId on enum members in protobuf encoding
- Move Polymorphic and sealed kinds from UnionKind to special PolymorphicKind
- Sealed classes serialization & generated serializers for enum classes (@SerialInfo support)
- Objects serialization
- Don't use deprecated UTF8<>ByteArray conversions in Native
- Improve error message when static non-generic serializer can't be found
- Support optional values for typesafe config format
-
v0.13.0 Changes
September 12, 2019- Add mingwX86 target (#556)
- Replace KClass.simpleName with artificial expect/actual with java.lang.Class.simpleName on JVM to overcome requirement for kotlin-reflect.jar (#549)
- Update Gradle to 5.6.1 (therefore Gradle metadata to 1.0)
- Fix incorrect index supply during map deserialization when READ_ALL was used (#526)
- Serializers for primitive arrays (ByteArray etc)
- Hide NullableSerializer, introduce '.nullable' extension instead
- Fix the library to not create a stack overflow exception when creating a MissingDescriptorException. (#545)