kotlinx.serialization v1.0.0-RC Release Notes
Release Date: 2020-08-17 // over 3 years ago-
๐ 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)