Skip to content

Analyzing Types (Kotlinx.Serialization)

Type analysis is the first step to generating a schema. The step looks at all involved Kotlin or Java types and extracts information about methods, fields, subtypes, supertypes, type parameters and more.

Using Reflection

Information about type analysis using reflection

Basics

@Serializable
class ExampleClass(
    val text: String,
    val number: Int?
)

With the analyzeTypeUsingKotlinxSerialization()-step, information about a given input type is extracted and resulting information about the type as well as other referenced types, e.g. "ExampleClass", "String" and "Int" is returned to be used as inputs for further steps.

The step can be configured to specify which information should be included in the output and in what format.

initial<ExampleClass>().analyzeTypeUsingKotlinxSerialization {
    //...
}
Type Parameters

Kotlinx.Serialization does not provide enough information to reason about type parameters forcing the analysis step to treat classes more carefully and avoid collisions which may lead to unwanted side effects during schema generation.
This more careful behaviour can be disabled for specific types that are known to never have any type parameters with the "markNotParameterized" configuration option.
This configuration may not be required for most situations, but can be used to manually resolve issues.

initial<ExampleClass>().analyzeTypeUsingKotlinxSerialization {
    markNotParameterized<SimpleClass>()
    markNotParameterized(typeOf<SimpleClass>())
    markNotParameterized("example.types.MySimpleClass")
}
Configuration Options

API Reference

Required Dependencies 
implementation("io.github.smiley4:schema-kenerator-serialization:$version")

implementation 'io.github.smiley4:schema-kenerator-serialization:$version'

<dependency>
    <groupId>io.github.smiley4</groupId>
    <artifactId>schema-kenerator-serialization</artifactId>
    <version>${version}</version>
</dependency>

Inheritance and Subtypes

Subtypes of sealed classes and interfaces are detected and included automatically.

sealed class SealedParent { //(1)!
    class ChildOne : SealedParent()
    class ChildTwo : SealedParent()
}
  1. Sealed class SealedParent with two subtypes ChildOne and ChildTwo.
initial<SealedParent>().analyzeTypeUsingKotlinxSerialization()
Required Dependencies 
implementation("io.github.smiley4:schema-kenerator-serialization:$version")

implementation 'io.github.smiley4:schema-kenerator-serialization:$version'

<dependency>
    <groupId>io.github.smiley4</groupId>
    <artifactId>schema-kenerator-serialization</artifactId>
    <version>${version}</version>
</dependency>

Discriminator Properties

A discriminator is used to differentiate between subtypes when (de-)serializing types, i.e. to know which subtype we are dealing with. This property is often times not included as a field in the class itself, but configured e.g. via an annotation. This property can also be added to the type information, e.g. to be later included in generated schemas.

Default Property

sealed class SealedParent { //(1)!
    class ChildOne : SealedParent()
    class ChildTwo : SealedParent()
}
  1. Class SealedParent with two subtypes ChildOne and ChildTwo to differentiate between.
initial<SealedParent>()
    .analyzeTypeUsingKotlinxSerialization()
    .addDiscriminatorProperty("_type") //(1)!
  1. Makes sure a property _type exists for all types that have subtypes.

An "annotation" with name discriminator_marker is added to the property to mark it and make it possible to find it later, e.g. when generating schemas.
If a property with the name already exists, the maker annotation is added to this property instead.
If a (different) property with marked with the annotation is already present, the step will NOT add the new specified property.

Required Dependencies 

implementation("io.github.smiley4:schema-kenerator-core:$version")

implementation("io.github.smiley4:schema-kenerator-serialization:$version")


implementation 'io.github.smiley4:schema-kenerator-core:$version'

implementation 'io.github.smiley4:schema-kenerator-serialization:$version'


<dependency>
    <groupId>io.github.smiley4</groupId>
    <artifactId>schema-kenerator-core</artifactId>
    <version>${version}</version>
</dependency>

<dependency>
    <groupId>io.github.smiley4</groupId>
    <artifactId>schema-kenerator-serialization</artifactId>
    <version>${version}</version>
</dependency>

Kotlinx.Serialization @JsonClassDiscriminator-annotation

A discriminator property with a name specified with the @JsonClassDiscriminator-annotation can be added to all types that have known subtypes. 

@Serializable
@JsonClassDiscriminator("_type") //(1)!
sealed class ParentDiscriminatorKotlinx { //(2)!
    @Serializable class ChildOne : SealedParent()
    @Serializable class ChildTwo : SealedParent()
}
  1. JsonClassDiscriminator annotation defining the name of the discriminator property.
  2. Class ParentDiscriminatorKotlinx with two subtypes ChildOne and ChildTwo to differentiate between.
ypeOf<ParentDiscriminatorKotlinx>()
    .analyzeTypeUsingKotlinxSerialization()
    .addJsonClassDiscriminatorProperty() //(1)!
  1. Adds a property with the name specified in @JsonClassDiscriminator to all annotated types with subtypes.
Required Dependencies 
implementation("io.github.smiley4:schema-kenerator-serialization:$version")

implementation 'io.github.smiley4:schema-kenerator-serialization:$version'

<dependency>
    <groupId>io.github.smiley4</groupId>
    <artifactId>schema-kenerator-serialization</artifactId>
    <version>${version}</version>
</dependency>