Skip to main content

Data classes in public API

DiagnosticDATA_CLASS_PUBLIC_API
Default severityError
Gradle propertydataClassPublicApi
Exemption@IntentionallyDataClass

What it reports​

A data class in the public API or declared as @PublishedApi internal.

public data class Point(
public val x: Int,
public val y: Int,
)

Rationale​

A data class exposes its primary constructor properties through these generated members:

  • copy: One parameter for each property, in declaration order.
  • componentN: One function for each property, in declaration order.
  • equals, hashCode, and toString

Data classes can define equals, hashCode, and toString, or inherit final implementations. Kotlin still generates copy and componentN.

In a regular class, you choose which members to declare. Poko generates equals, hashCode, and toString without copy or componentN.

Callers can use the generated API:

public data class Region(
public val width: Int,
public val height: Int,
)
private fun clientCode() {
val region = Region(1920, 1080)
val cropped = region.copy(1280) // positional copy
val (width, height) = region // componentN destructuring
val same = region == Region(1920, 1080) // structural equality
}

The generated members also have these behaviors:

  • The copy function is shallow, so the copy shares references to objects stored in properties.

  • A change to a primary constructor property can change the instance's hash code. This can prevent lookup in hash-based collections.

  • The generated members exclude properties declared in the class body:

    public data class Session(
    public val value: String,
    ) {
    public val createdAt: Long = System.currentTimeMillis()
    }

    Sessions with the same value compare equal and have the same string representation, even if their createdAt values differ. A call to copy initializes createdAt again.

Compatibility overloads​

If Region gains an offsetX property, existing compiled callers still need the old constructor and copy signatures. The secondary constructor and copy overload below restore calls that pass both width and height.

public data class Region(
public val width: Int,
public val height: Int,
public val offsetX: Int,
) {
public constructor(width: Int, height: Int) : this(width, height, 0)
public fun copy(width: Int, height: Int): Region = Region(width, height, offsetX)
}

On the JVM, compiled calls that omit copy arguments use copy$default. This example doesn't restore that method's old signature.

From the Kotlin library authors' guide, Avoid using data classes in your API:

It's possible to work around these issues by manually writing a secondary constructor and overriding the copy method. However, the effort involved negates the convenience of using a data class.

Don't​

public data class Coordinates(
public val x: Int,
public val y: Int,
)

Do​

public class Coordinates(
public val x: Int,
public val y: Int,
)

Notes​

  • data objects aren't reported.
  • A non-public primary constructor or non-public properties don't exempt a data class.

Exemption​

If this is intended, apply @IntentionallyDataClass to the class.

Use the exemption when the declaration is part of the API design or must stay for backwards compatibility.

@IntentionallyDataClass(reason = ExemptionReason.API_DESIGN)
public data class Coordinates(
public val x: Int,
public val y: Int,
)

Configuration​

build.gradle.kts
apiWatchdog {
dataClassPublicApi = WatchdogSeverity.ERROR
}

For a direct compiler call:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=DATA_CLASS_PUBLIC_API:error

See also​