When I have a contract gradle module, containing `...

# gradle

[ursus]

When I have a contract gradle module, containing @Serializable annotation

interface UserApiClient {
    suspend fun user(): ApiUser
}

@Serializable
data class ApiUser(
    val userId: Long,
    val username: String?,
    ..
)

is or is not @Serializable part of public interface?

i.e. should I kotlinx.serialization runtime library be api or implementation?

[Vampire]

Imho annotations are always compileOnly.
But here this will probably not apply as there is more in kotlinx.serialization.
Not sure though if what is generated by the plugin is part of the API, but it might be.

If in doubt - or generally - use the dependency-analysis-gradle-plugin.
It of course has some blind spots and edge cases, but generally it gives pretty good advices where which library should go to.

[ursus]

analysis plugin says to add it .. but my thinking was exactly yours.. its a compile time marker, not part of signature..unless im wrong 😄

[mbonnin]

If your @Serializable classes are public, their serializers are public as well. See https://github.com/Kotlin/kotlinx.serialization/issues/2108#issuecomment-1326695476

[ursus]

I wouldn't really mind if the serializers weren't available outside

[mbonnin]

This is my feature request in that issue but it’s currently not possible

[Vampire]

but my thinking was exactly yours.. its a compile time marker, not part of signature

The annotation, yes.
But the point is, that your classes contain generated code added by the kxs serializer Gradle plugin.
And whether that code contains kxs classes in the public API is the question.

The dependency-analysis-gradle-plugin unfortunately does a wrong decision for annotations that are runtime retention imho

[Vampire]

https://github.com/autonomousapps/dependency-analysis-gradle-plugin/issues/1210

[ursus]

okay so @Serialzable is not part of signature, but codegen adds stuff to binary interface therefore api kotlinx.serialization.json

[Vampire]

Not json, but core I guess

[ursus]

right but where will I specify I actually want json?

[ursus]

api core
implementation json

?

[mbonnin]

I’d say so. The serializers are format agnostic

[Vampire]

image.png

[ursus]

ugh too much typing 😄

[Vampire]

That class is core, so core is API as it is return type of public method

[Vampire]

As Martin said, the format should be separate thing that you just use at runtime, so should most probably not be part or the API

[ursus]

so json artifact contains Json etc?

[Vampire]

dagp will say so if you used some format-specific annotations like JsonName and so on

[Vampire]

When using dagp, you can also not just look at the advices.
You can also use the reason task to at least see one or some of the reasons for the given advice.

[Vampire]

And it generates lots of intermediate files with the information about which uses what where

[Vampire]

So you could also search in them what json-artifact classes appear and if it is just annotations, I'd say it is compileOnly, but you probably use it in the implementation of your methods, so then implementation

[ursus]

im a bit confused, how can I compileOnly if the annots are core?

[ursus]

or are they separate?

[Vampire]

I said "if it is just annotations", so no other classes.
And I talked about format-specific annotations like JsonName.
If you for example do not do any serialization but only make a library that can be used with KxS properly, then you might just have some format-specific annotations but no other classes.

[Vampire]

The core annotations of course will not be compile only, as the KSerializer is api and api > implementation > compileOnly

[ursus]

yea, makes sense, wouldn't help much
thanks!