1# Kotlin Serialization Guide 2 3Kotlin Serialization is a cross-platform and multi-format framework for data serialization—converting 4trees of objects to strings, byte arrays, or other _serial_ representations and back. 5Kotlin Serialization fully supports and enforces the Kotlin type system, making sure only valid 6objects can be deserialized. 7 8Kotlin Serialization is not just a library. It is a compiler plugin that is bundled with the Kotlin 9compiler distribution itself. Build configuration is explained in [README.md](../README.md#setup). 10Once the project is set up, we can start serializing some classes. 11 12## Table of contents 13 14**Chapter 1.** [Basic Serialization](basic-serialization.md) (**start reading here**) 15<!--- TOC_REF basic-serialization.md --> 16* <a name='basics'></a>[Basics](basic-serialization.md#basics) 17 * <a name='json-encoding'></a>[JSON encoding](basic-serialization.md#json-encoding) 18 * <a name='json-decoding'></a>[JSON decoding](basic-serialization.md#json-decoding) 19* <a name='serializable-classes'></a>[Serializable classes](basic-serialization.md#serializable-classes) 20 * <a name='backing-fields-are-serialized'></a>[Backing fields are serialized](basic-serialization.md#backing-fields-are-serialized) 21 * <a name='constructor-properties-requirement'></a>[Constructor properties requirement](basic-serialization.md#constructor-properties-requirement) 22 * <a name='data-validation'></a>[Data validation](basic-serialization.md#data-validation) 23 * <a name='optional-properties'></a>[Optional properties](basic-serialization.md#optional-properties) 24 * <a name='optional-property-initializer-call'></a>[Optional property initializer call](basic-serialization.md#optional-property-initializer-call) 25 * <a name='required-properties'></a>[Required properties](basic-serialization.md#required-properties) 26 * <a name='transient-properties'></a>[Transient properties](basic-serialization.md#transient-properties) 27 * <a name='defaults-are-not-encoded-by-default'></a>[Defaults are not encoded by default](basic-serialization.md#defaults-are-not-encoded-by-default) 28 * <a name='nullable-properties'></a>[Nullable properties](basic-serialization.md#nullable-properties) 29 * <a name='type-safety-is-enforced'></a>[Type safety is enforced](basic-serialization.md#type-safety-is-enforced) 30 * <a name='referenced-objects'></a>[Referenced objects](basic-serialization.md#referenced-objects) 31 * <a name='no-compression-of-repeated-references'></a>[No compression of repeated references](basic-serialization.md#no-compression-of-repeated-references) 32 * <a name='generic-classes'></a>[Generic classes](basic-serialization.md#generic-classes) 33 * <a name='serial-field-names'></a>[Serial field names](basic-serialization.md#serial-field-names) 34<!--- END --> 35 36**Chapter 2.** [Builtin Classes](builtin-classes.md) 37 38<!--- TOC_REF builtin-classes.md --> 39* <a name='primitives'></a>[Primitives](builtin-classes.md#primitives) 40 * <a name='numbers'></a>[Numbers](builtin-classes.md#numbers) 41 * <a name='long-numbers'></a>[Long numbers](builtin-classes.md#long-numbers) 42 * <a name='long-numbers-as-strings'></a>[Long numbers as strings](builtin-classes.md#long-numbers-as-strings) 43 * <a name='enum-classes'></a>[Enum classes](builtin-classes.md#enum-classes) 44 * <a name='serial-names-of-enum-entries'></a>[Serial names of enum entries](builtin-classes.md#serial-names-of-enum-entries) 45* <a name='composites'></a>[Composites](builtin-classes.md#composites) 46 * <a name='pair-and-triple'></a>[Pair and triple](builtin-classes.md#pair-and-triple) 47 * <a name='lists'></a>[Lists](builtin-classes.md#lists) 48 * <a name='sets-and-other-collections'></a>[Sets and other collections](builtin-classes.md#sets-and-other-collections) 49 * <a name='deserializing-collections'></a>[Deserializing collections](builtin-classes.md#deserializing-collections) 50 * <a name='maps'></a>[Maps](builtin-classes.md#maps) 51 * <a name='unit-and-singleton-objects'></a>[Unit and singleton objects](builtin-classes.md#unit-and-singleton-objects) 52 * <a name='duration'></a>[Duration](builtin-classes.md#duration) 53* <a name='nothing'></a>[Nothing](builtin-classes.md#nothing) 54<!--- END --> 55 56**Chapter 3.** [Serializers](serializers.md) 57 58<!--- TOC_REF serializers.md --> 59* <a name='introduction-to-serializers'></a>[Introduction to serializers](serializers.md#introduction-to-serializers) 60 * <a name='plugin-generated-serializer'></a>[Plugin-generated serializer](serializers.md#plugin-generated-serializer) 61 * <a name='plugin-generated-generic-serializer'></a>[Plugin-generated generic serializer](serializers.md#plugin-generated-generic-serializer) 62 * <a name='builtin-primitive-serializers'></a>[Builtin primitive serializers](serializers.md#builtin-primitive-serializers) 63 * <a name='constructing-collection-serializers'></a>[Constructing collection serializers](serializers.md#constructing-collection-serializers) 64 * <a name='using-top-level-serializer-function'></a>[Using top-level serializer function](serializers.md#using-top-level-serializer-function) 65* <a name='custom-serializers'></a>[Custom serializers](serializers.md#custom-serializers) 66 * <a name='primitive-serializer'></a>[Primitive serializer](serializers.md#primitive-serializer) 67 * <a name='delegating-serializers'></a>[Delegating serializers](serializers.md#delegating-serializers) 68 * <a name='composite-serializer-via-surrogate'></a>[Composite serializer via surrogate](serializers.md#composite-serializer-via-surrogate) 69 * <a name='hand-written-composite-serializer'></a>[Hand-written composite serializer](serializers.md#hand-written-composite-serializer) 70 * <a name='sequential-decoding-protocol-experimental'></a>[Sequential decoding protocol (experimental)](serializers.md#sequential-decoding-protocol-experimental) 71 * <a name='serializing-3rd-party-classes'></a>[Serializing 3rd party classes](serializers.md#serializing-3rd-party-classes) 72 * <a name='passing-a-serializer-manually'></a>[Passing a serializer manually](serializers.md#passing-a-serializer-manually) 73 * <a name='specifying-serializer-on-a-property'></a>[Specifying serializer on a property](serializers.md#specifying-serializer-on-a-property) 74 * <a name='specifying-serializer-for-a-particular-type'></a>[Specifying serializer for a particular type](serializers.md#specifying-serializer-for-a-particular-type) 75 * <a name='specifying-serializers-for-a-file'></a>[Specifying serializers for a file](serializers.md#specifying-serializers-for-a-file) 76 * <a name='specifying-serializer-globally-using-typealias'></a>[Specifying serializer globally using typealias](serializers.md#specifying-serializer-globally-using-typealias) 77 * <a name='custom-serializers-for-a-generic-type'></a>[Custom serializers for a generic type](serializers.md#custom-serializers-for-a-generic-type) 78 * <a name='format-specific-serializers'></a>[Format-specific serializers](serializers.md#format-specific-serializers) 79* <a name='contextual-serialization'></a>[Contextual serialization](serializers.md#contextual-serialization) 80 * <a name='serializers-module'></a>[Serializers module](serializers.md#serializers-module) 81 * <a name='contextual-serialization-and-generic-classes'></a>[Contextual serialization and generic classes](serializers.md#contextual-serialization-and-generic-classes) 82* <a name='deriving-external-serializer-for-another-kotlin-class-experimental'></a>[Deriving external serializer for another Kotlin class (experimental)](serializers.md#deriving-external-serializer-for-another-kotlin-class-experimental) 83 * <a name='external-serialization-uses-properties'></a>[External serialization uses properties](serializers.md#external-serialization-uses-properties) 84<!--- END --> 85 86**Chapter 4.** [Polymorphism](polymorphism.md) 87 88<!--- TOC_REF polymorphism.md --> 89* <a name='closed-polymorphism'></a>[Closed polymorphism](polymorphism.md#closed-polymorphism) 90 * <a name='static-types'></a>[Static types](polymorphism.md#static-types) 91 * <a name='designing-serializable-hierarchy'></a>[Designing serializable hierarchy](polymorphism.md#designing-serializable-hierarchy) 92 * <a name='sealed-classes'></a>[Sealed classes](polymorphism.md#sealed-classes) 93 * <a name='custom-subclass-serial-name'></a>[Custom subclass serial name](polymorphism.md#custom-subclass-serial-name) 94 * <a name='concrete-properties-in-a-base-class'></a>[Concrete properties in a base class](polymorphism.md#concrete-properties-in-a-base-class) 95 * <a name='objects'></a>[Objects](polymorphism.md#objects) 96* <a name='open-polymorphism'></a>[Open polymorphism](polymorphism.md#open-polymorphism) 97 * <a name='registered-subclasses'></a>[Registered subclasses](polymorphism.md#registered-subclasses) 98 * <a name='serializing-interfaces'></a>[Serializing interfaces](polymorphism.md#serializing-interfaces) 99 * <a name='property-of-an-interface-type'></a>[Property of an interface type](polymorphism.md#property-of-an-interface-type) 100 * <a name='static-parent-type-lookup-for-polymorphism'></a>[Static parent type lookup for polymorphism](polymorphism.md#static-parent-type-lookup-for-polymorphism) 101 * <a name='explicitly-marking-polymorphic-class-properties'></a>[Explicitly marking polymorphic class properties](polymorphism.md#explicitly-marking-polymorphic-class-properties) 102 * <a name='registering-multiple-superclasses'></a>[Registering multiple superclasses](polymorphism.md#registering-multiple-superclasses) 103 * <a name='polymorphism-and-generic-classes'></a>[Polymorphism and generic classes](polymorphism.md#polymorphism-and-generic-classes) 104 * <a name='merging-library-serializers-modules'></a>[Merging library serializers modules](polymorphism.md#merging-library-serializers-modules) 105 * <a name='default-polymorphic-type-handler-for-deserialization'></a>[Default polymorphic type handler for deserialization](polymorphism.md#default-polymorphic-type-handler-for-deserialization) 106 * <a name='default-polymorphic-type-handler-for-serialization'></a>[Default polymorphic type handler for serialization](polymorphism.md#default-polymorphic-type-handler-for-serialization) 107<!--- END --> 108 109**Chapter 5.** [JSON Features](json.md) 110 111<!--- TOC_REF json.md --> 112* <a name='json-configuration'></a>[Json configuration](json.md#json-configuration) 113 * <a name='pretty-printing'></a>[Pretty printing](json.md#pretty-printing) 114 * <a name='lenient-parsing'></a>[Lenient parsing](json.md#lenient-parsing) 115 * <a name='ignoring-unknown-keys'></a>[Ignoring unknown keys](json.md#ignoring-unknown-keys) 116 * <a name='alternative-json-names'></a>[Alternative Json names](json.md#alternative-json-names) 117 * <a name='coercing-input-values'></a>[Coercing input values](json.md#coercing-input-values) 118 * <a name='encoding-defaults'></a>[Encoding defaults](json.md#encoding-defaults) 119 * <a name='explicit-nulls'></a>[Explicit nulls](json.md#explicit-nulls) 120 * <a name='allowing-structured-map-keys'></a>[Allowing structured map keys](json.md#allowing-structured-map-keys) 121 * <a name='allowing-special-floating-point-values'></a>[Allowing special floating-point values](json.md#allowing-special-floating-point-values) 122 * <a name='class-discriminator-for-polymorphism'></a>[Class discriminator for polymorphism](json.md#class-discriminator-for-polymorphism) 123 * <a name='class-discriminator-output-mode'></a>[Class discriminator output mode](json.md#class-discriminator-output-mode) 124 * <a name='decoding-enums-in-a-case-insensitive-manner'></a>[Decoding enums in a case-insensitive manner](json.md#decoding-enums-in-a-case-insensitive-manner) 125 * <a name='global-naming-strategy'></a>[Global naming strategy](json.md#global-naming-strategy) 126* <a name='json-elements'></a>[Json elements](json.md#json-elements) 127 * <a name='parsing-to-json-element'></a>[Parsing to Json element](json.md#parsing-to-json-element) 128 * <a name='types-of-json-elements'></a>[Types of Json elements](json.md#types-of-json-elements) 129 * <a name='json-element-builders'></a>[Json element builders](json.md#json-element-builders) 130 * <a name='decoding-json-elements'></a>[Decoding Json elements](json.md#decoding-json-elements) 131 * <a name='encoding-literal-json-content-experimental'></a>[Encoding literal Json content (experimental)](json.md#encoding-literal-json-content-experimental) 132 * <a name='serializing-large-decimal-numbers'></a>[Serializing large decimal numbers](json.md#serializing-large-decimal-numbers) 133 * <a name='using-jsonunquotedliteral-to-create-a-literal-unquoted-value-of-null-is-forbidden'></a>[Using `JsonUnquotedLiteral` to create a literal unquoted value of `null` is forbidden](json.md#using-jsonunquotedliteral-to-create-a-literal-unquoted-value-of-null-is-forbidden) 134* <a name='json-transformations'></a>[Json transformations](json.md#json-transformations) 135 * <a name='array-wrapping'></a>[Array wrapping](json.md#array-wrapping) 136 * <a name='array-unwrapping'></a>[Array unwrapping](json.md#array-unwrapping) 137 * <a name='manipulating-default-values'></a>[Manipulating default values](json.md#manipulating-default-values) 138 * <a name='content-based-polymorphic-deserialization'></a>[Content-based polymorphic deserialization](json.md#content-based-polymorphic-deserialization) 139 * <a name='under-the-hood-experimental'></a>[Under the hood (experimental)](json.md#under-the-hood-experimental) 140 * <a name='maintaining-custom-json-attributes'></a>[Maintaining custom JSON attributes](json.md#maintaining-custom-json-attributes) 141<!--- END --> 142 143**Chapter 6.** [Alternative and custom formats (experimental)](formats.md) 144 145<!--- TOC_REF formats.md --> 146* <a name='cbor-experimental'></a>[CBOR (experimental)](formats.md#cbor-experimental) 147 * <a name='ignoring-unknown-keys'></a>[Ignoring unknown keys](formats.md#ignoring-unknown-keys) 148 * <a name='byte-arrays-and-cbor-data-types'></a>[Byte arrays and CBOR data types](formats.md#byte-arrays-and-cbor-data-types) 149* <a name='protobuf-experimental'></a>[ProtoBuf (experimental)](formats.md#protobuf-experimental) 150 * <a name='field-numbers'></a>[Field numbers](formats.md#field-numbers) 151 * <a name='integer-types'></a>[Integer types](formats.md#integer-types) 152 * <a name='lists-as-repeated-fields'></a>[Lists as repeated fields](formats.md#lists-as-repeated-fields) 153 * <a name='packed-fields'></a>[Packed fields](formats.md#packed-fields) 154 * <a name='protobuf-schema-generator-experimental'></a>[ProtoBuf schema generator (experimental)](formats.md#protobuf-schema-generator-experimental) 155* <a name='properties-experimental'></a>[Properties (experimental)](formats.md#properties-experimental) 156* <a name='custom-formats-experimental'></a>[Custom formats (experimental)](formats.md#custom-formats-experimental) 157 * <a name='basic-encoder'></a>[Basic encoder](formats.md#basic-encoder) 158 * <a name='basic-decoder'></a>[Basic decoder](formats.md#basic-decoder) 159 * <a name='sequential-decoding'></a>[Sequential decoding](formats.md#sequential-decoding) 160 * <a name='adding-collection-support'></a>[Adding collection support](formats.md#adding-collection-support) 161 * <a name='adding-null-support'></a>[Adding null support](formats.md#adding-null-support) 162 * <a name='efficient-binary-format'></a>[Efficient binary format](formats.md#efficient-binary-format) 163 * <a name='format-specific-types'></a>[Format-specific types](formats.md#format-specific-types) 164<!--- END --> 165 166**Appendix A.** [Serialization and value classes (IR-only)](value-classes.md) 167 168<!--- TOC_REF value-classes.md --> 169* <a name='serializable-value-classes'></a>[Serializable value classes](value-classes.md#serializable-value-classes) 170* <a name='unsigned-types-support-json-only'></a>[Unsigned types support (JSON only)](value-classes.md#unsigned-types-support-json-only) 171* <a name='using-value-classes-in-your-custom-serializers'></a>[Using value classes in your custom serializers](value-classes.md#using-value-classes-in-your-custom-serializers) 172<!--- END --> 173