Reflection, Annotations & Serialization

A KClass is Kotlin's runtime handle to a class. You get it with String::class for a type or instance::class for an object. It exposes Kotlin features like properties and nullability; java.lang.Class only knows the Java view.

A single Kotlin property compiles into several JVM elements: a field, a getter, a constructor parameter. Use-site targets like @field: or @get: tell the compiler which one the annotation lands on, since each may need it.

KCallable is the common type for anything you can call: functions and properties. KFunction is invoked with call(args). KProperty has a getter you read with get(receiver); mutable ones (KMutableProperty) also have a setter.

The JVM erases generics, so List<String> looks like List at runtime. Kotlin's typeOf<T>() captures the full type, and reified type parameters in inline functions keep T available so you can inspect or use it.

The @Serializable compiler plugin writes a serializer for your class while it compiles, so no runtime reflection is needed. Reflection-based tools instead inspect the class at runtime, which is slower and harder to use on native or minified targets.

A callable reference points at an existing function or property by name using the :: operator, so you can pass it around instead of writing a lambda. Example: list.map(String::length).

You get a KFunction (for example from ::myFunc or a KClass member) and call its call(...) method, passing the arguments in the same order the function declares them. For a member function, the first argument is the receiver object.

Basic things like ::class work without extra setup. Richer reflection (reading properties, functions, parameters, supertypes) needs the separate kotlin-reflect library added to your build.

Use ::class. On a value like x::class you get the real runtime type of that object. On a type name like String::class you get that exact declared class. Both give a KClass, Kotlin's reflection handle for a class.

Kotlin has two class objects. Use the .java property to turn a Kotlin class into a Java Class, and the .kotlin property to turn a Java Class back into a Kotlin one.

Annotation parameters can only be simple compile-time values: numbers, Boolean, Char, String, enums, a class reference, another annotation, and arrays of those. You cannot use arbitrary objects like a List or a date.

Write a class with the annotation class keywords, for example annotation class Loggable. Then put @Loggable in front of a function, property, or class to mark it.

Meta-annotations are annotations you put on another annotation's declaration to describe how it behaves. The built-in ones are @Retention, @Target, @MustBeDocumented, and @Repeatable.

Use Kotlin reflection: get the class with ::class, look at its annotations list, or call findAnnotation. The annotation only shows up at runtime if it was declared with RUNTIME retention.

@Retention says how long the annotation is kept: source only, in the class file, or readable at runtime. @Target says where you can put it: on classes, functions, properties, parameters, and so on.

@Contextual tells the serializer: don't pick a serializer at compile time for this property. Look one up at runtime from a registered module. You use it for types you can't annotate, like java.util.Date.

A KSerializer<T> is the object that knows how to turn a value of type T into a stream of data and read it back. It provides a serialize function, a deserialize function, and a descriptor describing the type.

Put @SerialName("json_key") on the property. The Kotlin field keeps its name in code, but the JSON uses the name you give. Useful when JSON uses snake_case but Kotlin uses camelCase.

Adding @Serializable tells a compiler plugin to generate the code that reads and writes the class. Because that code is built when you compile, the library doesn't have to inspect the class at runtime.

A SerializersModule is a registry that tells the serialization library how to handle types it cannot figure out on its own, like interfaces or open base classes with many possible subtypes.

It is a small class that tells the library exactly how to turn one type into data and back. You write one when the default behavior is wrong, for types you cannot annotate, or when the wire format must differ from your class.

Put checks in the class's init {} block using require(). Deserialization calls the real constructor, so the checks run too. Bad input throws instead of producing a broken object.

Mark the class with @Serializable, then call Json.encodeToString(obj) to get JSON text and Json.decodeFromString(text) to read it back. Json is the format instance that does the conversion.

JsonElement is a flexible in-memory tree for JSON when you don't have a fixed class. Its parts are JsonObject (key-value), JsonArray (list), and JsonPrimitive (string, number, boolean, or null). Use it when the JSON shape is unknown or changes.

Give the new property a default value. When the field is missing from the JSON, kotlinx.serialization uses the default, so old messages still load without errors.