serialization-guide.md

Kotlin Serialization Guide

Kotlin Serialization is a cross-platform and multi-format framework for data serialization—converting trees of objects to strings, byte arrays, or other serial representations and back. Kotlin Serialization fully supports and enforces the Kotlin type system, making sure only valid objects can be deserialized.

Kotlin Serialization is not just a library. It is a compiler plugin that is bundled with the Kotlin compiler distribution itself. Build configuration is explained in README.md. Once the project is set up, we can start serializing some classes.

Table of contents

Chapter 1. Basic Serialization (start reading here)

• Basics
  • JSON encoding
  • JSON decoding
• Serializable classes
  • Backing fields are serialized
  • Constructor properties requirement
  • Data validation
  • Optional properties
  • Optional property initializer call
  • Required properties
  • Transient properties
  • Defaults are not encoded
  • Nullable properties
  • Type safety is enforced
  • Referenced objects
  • No compression of repeated references
  • Generic classes
  • Serial field names

Chapter 2. Builtin Classes

• Primitives
  • Numbers
  • Long numbers
  • Long numbers as strings
  • Enum classes
  • Serial names of enum entries
• Composites
  • Pair and triple
  • Lists
  • Sets and other collections
  • Deserializing collections
  • Maps
  • Unit and singleton objects

Chapter 3. Serializers

• Introduction to serializers
  • Plugin-generated serializer
  • Plugin-generated generic serializer
  • Builtin primitive serializers
  • Constructing collection serializers
  • Using top-level serializer function
• Custom serializers
  • Primitive serializer
  • Composite serializer via surrogate
  • Hand-written composite serializer
  • Sequential decoding protocol (experimental)
  • Serializing 3rd party classes
  • Passing a serializer manually
  • Specifying serializer on a property
  • Specifying serializers for a file
  • Custom serializers for a generic type
  • Format-specific serializers
• Contextual serialization
  • Serializers module
  • Contextual serialization and generic classes
• Deriving external serializer for another Kotlin class (experimental)
  • External serialization uses properties

Chapter 4. Polymorphism

• Closed polymorphism
  • Static types
  • Designing serializable hierarchy
  • Sealed classes
  • Custom subclass serial name
  • Concrete properties in a base class
  • Objects
• Open polymorphism
  • Registered subclasses
  • Serializing interfaces
  • Property of an interface type
  • Static parent type lookup for polymorphism
  • Explicitly marking polymorphic class properties
  • Registering multiple superclasses
  • Polymorphism and generic classes
  • Merging library serializers modules
  • Default polymorphic type handler for deserialization

Chapter 5. JSON Features

• Json configuration
  • Pretty printing
  • Lenient parsing
  • Ignoring unknown keys
  • Alternative Json names
  • Coercing input values
  • Encoding defaults
  • Allowing structured map keys
  • Allowing special floating-point values
  • Class discriminator
• Json elements
  • Parsing to Json element
  • Subtypes of Json elements
  • Json element builders
  • Decoding Json element
• Json transformations
  • Array wrapping
  • Array unwrapping
  • Manipulating default values
  • Content-based polymorphic deserialization
  • Under the hood (experimental)
  • Maintaining custom JSON attributes

Chapter 6. Alternative and custom formats (experimental)

• CBOR (experimental)
  • Ignoring unknown keys
  • Byte arrays and CBOR data types
• ProtoBuf (experimental)
  • Field numbers
  • Integer types
  • Lists as repeated fields
• Properties (experimental)
• Custom formats (experimental)
  • Basic encoder
  • Basic decoder
  • Sequential decoding
  • Adding collection support
  • Adding null support
  • Efficient binary format
  • Format-specific types

Appendix A. Serialization and inline classes (experimental, IR-specific)

• Serializable inline classes
• Unsigned types support (JSON only)
• Using inline classes in your custom serializers