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 by default
  • 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
  • Duration
• Nothing

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
  • Delegating serializers
  • Composite serializer via surrogate
  • Handwritten composite serializer
  • Sequential decoding protocol (experimental)
  • Serializing 3rd party classes
  • Passing a serializer manually
  • Specifying a serializer on a property
  • Specifying a serializer for a particular type
  • Specifying serializers for a file
  • Specifying a serializer globally using a typealias
  • Custom serializers for a generic type
  • Format-specific serializers
• Simultaneous use of plugin-generated and custom 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
  • Default polymorphic type handler for serialization

Chapter 5. JSON Features

• Json configuration
  • Pretty printing
  • Lenient parsing
  • Ignoring unknown keys
  • Alternative Json names
  • Encoding defaults
  • Explicit nulls
  • Coercing input values
  • Allowing structured map keys
  • Allowing special floating-point values
  • Class discriminator for polymorphism
  • Class discriminator output mode
  • Decoding enums in a case-insensitive manner
  • Global naming strategy
  • Base64
• Json elements
  • Parsing to Json element
  • Types of Json elements
  • Json element builders
  • Decoding Json elements
  • Encoding literal Json content (experimental)
    • Serializing large decimal numbers
    • Using JsonUnquotedLiteral to create a literal unquoted value of null is forbidden
• Json transformations
  • Array wrapping
  • Array unwrapping
  • Manipulating default values
  • Content-based polymorphic deserialization
  • Extending the behavior of the plugin generated serializer
  • 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
  • Definite vs. Indefinite Length Encoding
  • Tags and Labels
  • Arrays
  • Custom CBOR-specific Serializers
• ProtoBuf (experimental)
  • Field numbers
  • Integer types
  • Lists as repeated fields
  • Packed fields
  • Oneof field (experimental)
    • Usage
    • Alternative
  • ProtoBuf schema generator (experimental)
• 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 value classes (IR-only)

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