All Versions
Latest Version
Avg Release Cycle
56 days
Latest Release
45 days ago

Changelog History
Page 2

  • 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)
  • 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 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.

    API changes


    Core API changes

    • stringify and parse are renamed to encodeToString and decodeFromString
    • parseJson and fromJson are renamed to parseToJsonElement and decodeFromJsonElement

    - Reified versions of methods are extracted to extensions

    ๐Ÿ— Json constructor is replaced with Json {} builder function, JsonConfiguration is deprecated in favor
    ๐Ÿ— of Json {} builder

    • All default Json implementations are removed

    - Json companion object extends Json

    ๐Ÿ”ง Json configuration

    • prettyPrintIndent allows only whitespaces
    • serializeSpecialFloatingPointValues is renamed to allowSpecialFloatingPointValues. It now affects both serialization and deserialization behaviour
    • unquoted 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 of JsonPrimitive 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 of put/add functions
    • jsonObject {} and json {} builders are renamed to buildJsonObject {} and buildJsonArray {}

    - Make all builders inline (#703)

    ๐Ÿ‘ JavaScript support

    • DynamicObjectParser is deprecated in the favor of Json.decodeFromDynamic extension functions

    - Json.encodeToDynamic extension is added as a counterpart to Json.decodeFromDynamic (former DynamicObjectParser) (#116)

    Other API changes:

    • JsonInput and JsonOutput are renamed to JsonDecoder and JsonEncoder
    • Methods in JsonTransformingSerializer are renamed to transformSerialize and transformDeserialize
    • JsonParametricSerializer is renamed to JsonContentPolymorphicSerializer

    - JsonEncodingException and JsonDecodingException are made internal

    ๐Ÿ› Bug fixes

    • IllegalStateException when null 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 and BinaryFormat are renamed and now follow the same naming scheme
    • stringify/parse are renamed to encodeToString/decodeFromString

    - encodeToByteArray/encodeToHexString/decodeFromByteArray/decodeFromHexString in BinaryFormat are introduced instead of dump/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 and SerialKind are moved to a separate kotlinx.serialization.descriptors package
    • ENUM and CONTEXTUAL kinds now extend SerialKind directly
    • PrimitiveDescriptor is renamed to PrimitiveSerialDescriptor
    • 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 in descriptor.getElementDescriptor(index) for List after upgrade to 0.20.0 is fixed (#739)

    SerializersModule-related API

    • SerialModule is renamed to SerializersModule
    • SerialModuleCollector is renamed to SerializersModuleCollector
    • 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 separate kotlinx.serialization.encoding package
    • Deprecated typeParameters argument in beginStructure/beginCollection methods
    • Deprecated updateSerializableValue and similar methods and UpdateMode enum
    • Renamed READ_DONE to DECODE_DONE
    • Make extensions inline where applicable

    - mockery (InputStream, ByteArrayInput, etc) is removed

    Serializer-related API

    • UnitSerializer is replaced with Unit.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 constructor is replaced with ProtoBuf {} builder function
    • ProtoBuf companion object now extends ProtoBuf
    • ProtoId is renamed to ProtoNumber, ProtoNumberType to ProtoIntegerType 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 of IllegalStateException 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 to Hocon, kotlinx-serialization-runtime-configparser artifact is renamed to kotlinx-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 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.
    • 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/ 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/

    ๐Ÿ”Œ 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:

    1. 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().

    2. Pay attention to the changed JsonConfiguration constructor arguments: instead of strictMode, now three different flags are available: ignoreUnknownKeys, isLenient, and serializeSpecialFloatingPointValues.

    3. 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/ 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 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)
  • 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)
  • v0.12.0 Changes

    August 23, 2019
    • Set up linuxArm32Hfp target (#535)
    • wasm32 is added as a build target (#518)
    • MPP (JVM & Native) serializer resolving from KType (via typeOf()/serializer() function)
    • Support maps and objects decoding when map size present in stream (fix #517)
    • Add proper SerialClassDescImpl.toString
    • Make JSON parser much more stricter; e.g. Prohibit all excessive separators in objects and maps
    • Robust JsonArray parsing
    • Improve json exceptions, add more contextual information, get rid of obsolete exception types
    • Prohibit trailing commas in JSON parser
    • Make the baseclass of the polymorphic serializer public to allow formats (#520)
    • Fix decoding for ProtoBuf when there are missing properties in the model. (#506)
    • Rework JsonException and related subclasses
    • Fix #480 (deserialization of complex map keys). Add tests for structured map keys in conjuction with polymorphism
    • Implement 'allowStructuredMapKeys' flag. Now this flag is required for serializing into JSON maps which keys are not primitive.
  • v0.11.1 Changes

    June 19, 2019
    • Fixed some bugs in compiler plugin for Native (#472, #478) (Kotlin 1.3.40 required)
    • Remove dependency on stdlib-jvm from common source set (Fixes #481)
    • Fix @UseSerializers argument type and clarify some docs
    • Support primitives (ints, strings, JsonLiterals, JsonNull, etc) on a top-level when saving/restoring JSON AST (#451)
    • Migrate to the new (Kotlin 1.3) MPP model
    • Add @SharedImmutable to default json module. Fixes #441 and #446
  • v0.11.0 Changes

    April 12, 2019

    ๐Ÿ”Œ Plugin:

    • Semantic change: Now properties with default values are @Optional by default, and properties without backing fields are @Transient by default.
    • Allow '@Serializable' on a type usage (fixes #367)
    • Auto-applying @Polymorphic for interfaces and serializable abstract classes
    • Do not enable PolymorphicSerializer without special annotation
    • Fix missing optionality of property when generating descriptor in Native
    • Fix impossibility to make @Optional field in a class hierarchy on JS
    • Add synthetic companion with .serializer() getter even if default serializer is overridden. (fixes #228)
    • Ban primitive arrays in JVM codegen too (fixes #260)
    • Don't generate writeSelf/internal constructor if corresponding serialize/deserialize aren't auto-generated
    • Support Serializable class hierarchies on Native and JS
    • Replace @Optional with @Required
    • Support classes with more than 32 serializable properties (fixes #164)
    • Make enums and interfaces not serializable internally. However, they still can be serialized using custom companion object. Fixes #138 and #304

    โš™ Runtime:

    • Introduce JsonBuilder and JsonConfiguration as a better mechanism for configuring and changing configuration of the JSON
    • Implement polymorphic serialization in JSON using class discriminator key
    • Force quoting for map keys (fixes #379)
    • Fix bug with endianness in Native for Longs/Doubles
    • Do not allow to mutate SerialModule in formats
    • Implement multiplatform (JVM, JS and Native) PolymorphicSerializer
    • Remove obsolete and poorly designed global class cache. Remove JVM-only PolymorphicSerializer
    • Replace old SerialModule with new one which: - Can not be installed, should be passed in format constructor - Has polymorphic resolve and contextual resolve - Has DSL for creation - Immutable, but can be combined or overwritten
    • Improve error message for unknown enum constant
    • Deprecate @Optional, introduce @Required
    • Use long instead of int in JsonLiteralSerializer
    • Json and protobuf schemas recording prototype
    • Change JsonObject so it would comply to a Map interface: .get should return null for a missing key Incompatibility with standard Map contract may bring a lot of problems, e.g. broken equals.
    • Make JsonElementSerializer public