0Pricing
Kotlin Academy · Lesson

Creating and Targeting Custom Annotations

Define annotations with retention policies and apply them to classes, functions, and properties.

Creating and Targeting Custom Annotations is a free Kotlin Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Kotlin Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Why Custom Annotations?

Annotations are metadata attached to declarations (classes, functions, properties, parameters). Custom annotations let you mark code for processing by frameworks, build tools (KSP/KAPT), or your own runtime logic.

Declaring an Annotation

Use the annotation class keyword. Annotation classes can have constructor parameters (only primitive types, String, KClass, enums, other annotations, or arrays thereof):

annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

Meta-Annotations: @Target

@Target restricts where the annotation can be used. Common targets: CLASS, FUNCTION, PROPERTY, FIELD, VALUE_PARAMETER, CONSTRUCTOR.

@Target(AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER)
annotation class Validate(val minLength: Int = 1, val maxLength: Int = 255)

@Retention: When Is the Annotation Available?

@Retention controls the annotation's lifetime:

  • SOURCE — discarded after compilation
  • BINARY — stored in .class file but not visible via reflection
  • RUNTIME — stored and visible at runtime (default for most use cases)
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Validate(val minLength: Int = 1)

@Repeatable: Applying the Same Annotation Multiple Times

By default, an annotation can only be applied once per declaration. Mark it @Repeatable to allow multiple applications:

@Repeatable
@Target(AnnotationTarget.FUNCTION)
annotation class Role(val name: String)

Annotating Constructors and Parameters

You can annotate constructor parameters and primary constructor properties. Use @field:, @get:, or @param: use-site targets to control which element receives the annotation:

data class User(
    @field:Validate(minLength = 2) val name: String,
    @field:Validate(minLength = 0, maxLength = 120) val email: String
)

Use-Site Targets

Kotlin generates multiple bytecode elements from one property (field, getter, setter, parameter). Use-site targets specify which one gets the annotation:

  • @field: the backing field
  • @get: the getter
  • @set: the setter
  • @param: constructor parameter

Annotating Classes

Annotations on a class are useful for marking it for framework processing (e.g., marking a class as serializable, injectable, or part of a specific module):

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
annotation class Repository

@Repository
class UserRepository

@MustBeDocumented

Adding @MustBeDocumented ensures the annotation appears in the generated API documentation. Use it for annotations that form part of your public API contract.

@MustBeDocumented
@Target(AnnotationTarget.CLASS)
annotation class PublicApi(val since: String)

Annotation Parameters: Defaults and Arrays

Parameters can have defaults and can accept arrays using the vararg keyword or explicit array types:

annotation class Roles(vararg val value: String)

@Roles("ADMIN", "EDITOR")
class AdminPanel

KClass Parameters in Annotations

Annotations can reference class types via KClass:

annotation class Serializer(val using: KClass<out Any>)

@Serializer(using = GsonAdapter::class)
class Event

Quick Check

Which @Retention value makes a custom annotation accessible via Kotlin reflection at runtime?

Recap: Custom Annotations

Key takeaways:

  • Declare with annotation class; parameters are limited to primitives, String, KClass, enums, and arrays
  • @Target — where it can be applied
  • @Retention — when it is available (use RUNTIME for reflection)
  • @Repeatable — allow multiple applications on one declaration
  • Use-site targets (@field:, @get:, etc.) control which bytecode element receives the annotation

Frequently asked questions

Is the “Creating and Targeting Custom Annotations” lesson free?

Yes — the full text of “Creating and Targeting Custom Annotations” is free to read here on the web, and the Kotlin Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Kotlin Academy course, upgrade to CoddyKit PRO.

What will I learn in “Creating and Targeting Custom Annotations”?

Define annotations with retention policies and apply them to classes, functions, and properties. You practise Kotlin Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Kotlin Academy?

No prior experience is required. Kotlin Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Creating and Targeting Custom Annotations” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Kotlin Academy lesson?

Yes. Every Kotlin Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Kotlin Reflection: KClass, KFunction, KProperty
  2. Creating and Targeting Custom Annotations
  3. Reading Annotations at Runtime
  4. Reflection-Based Validation and Mapping
← Back to Kotlin Academy