Jackson ObjectMapper Basics with the Kotlin Module

Jackson is the JSON engine that Spring Boot uses under the hood, and its central type is the ObjectMapper. An ObjectMapper is a configurable, thread-safe object that knows how to serialize Java/Kotlin objects into JSON text and deserialize JSON text back into objects. The two methods you will reach for constantly are writeValueAsString(value), which returns a JSON String, and readValue(json, Type), which parses a String (or stream) back into a typed instance. Because a configured mapper is thread-safe and relatively expensive to build, the idiomatic pattern is to create one instance and reuse it everywhere rather than constructing a fresh mapper per request.

Plain Jackson was designed for Java, and that creates friction with Kotlin. Out of the box, Jackson deserializes by calling a no-argument constructor and then setting fields one by one. Kotlin data classes typically have no no-arg constructor; they declare their properties as constructor parameters, often with val (immutable) and non-nullable types. If you point a vanilla ObjectMapper at a data class, you will hit errors like 'Cannot construct instance ... no Creators, like default constructor, exist', or you will silently lose Kotlin's null-safety guarantees because Jackson is happy to leave a non-null property null.

The fix is the jackson-module-kotlin dependency. Add it to your build (for example, com.fasterxml.jackson.module:jackson-module-kotlin on the classpath via Gradle) and register it on your mapper. This module teaches Jackson to read Kotlin's metadata: it can call the primary constructor with parameter names, it respects default parameter values when a JSON field is absent, and it honors nullability so that a missing or null JSON value for a non-nullable property fails fast with a MismatchedInputException (historically a MissingKotlinParameterException) instead of producing a corrupt object. In short, it makes idiomatic, immutable data classes 'just work' as your serialization model.

There are two common ways to wire it up. The terse, Kotlin-friendly way is the jacksonObjectMapper() factory function, which returns a ready-to-use ObjectMapper with the Kotlin module already registered. The explicit way is to start from a builder or a plain ObjectMapper and call registerKotlinModule() yourself: ObjectMapper().registerKotlinModule(). Both produce an equivalent result; jacksonObjectMapper() is simply a convenience wrapper. Use registerKotlinModule() when you are customizing a mapper you obtained from somewhere else and want to add Kotlin support to it.

Most real applications register more than one module. A typical setup chains registerKotlinModule() with JavaTimeModule (the jackson-datatype-jsr310 module) so that java.time types like Instant and LocalDate serialize as ISO-8601 strings instead of numeric timestamps. You will also frequently configure how unknown fields are handled: by default Jackson throws when it sees a JSON property that has no matching field, but calling configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false) makes the mapper tolerant of extra fields, which is valuable when you consume third-party APIs that add properties over time.

A subtle but important detail in Kotlin is reified type information for generic targets. Jackson needs the full type, including type parameters, to deserialize collections and generics correctly; readValue(json, List::class.java) would erase the element type. The jackson-module-kotlin library ships an inline reified extension, readValue<T>(json), that captures the complete generic type for you. So mapper.readValue<List<User>>(jsonArray) round-trips a list of User objects with the element type preserved, which is exactly what you want and far cleaner than building a TypeReference by hand.

In a Spring Boot 3 application you usually do not create the mapper yourself for controllers and @RequestBody binding, because Spring Boot auto-configures a Jackson ObjectMapper bean and, when jackson-module-kotlin is on the classpath, registers the Kotlin module automatically. Your job is mainly to add the dependency and, if you need tweaks, expose a Jackson2ObjectMapperBuilderCustomizer or set spring.jackson.* properties. You still construct mappers explicitly for non-HTTP work: writing to Kafka, persisting JSON columns, calling external services with a WebClient body codec, or any place you serialize by hand.

Two practices keep Jackson code healthy. First, treat the ObjectMapper as a shared, immutable-after-configuration singleton; configure it once at startup and inject or reference that single instance. Second, model your JSON with explicit data classes and let nullability express optionality: a non-nullable property means the field is required, a nullable property (or one with a default) means it is optional. When you combine reusable mappers, the Kotlin module, and well-typed data classes, serialization becomes nearly invisible, boilerplate-free plumbing, and your domain types stay clean and idiomatic.

import com.fasterxml.jackson.databind.ObjectMapper
import com.fasterxml.jackson.module.kotlin.registerKotlinModule
import com.fasterxml.jackson.module.kotlin.readValue

data class User(val id: Long, val name: String, val active: Boolean = true)

// Configure once, reuse everywhere (thread-safe after setup).
val mapper: ObjectMapper = ObjectMapper().registerKotlinModule()

fun main() {
    val user = User(id = 1, name = "Ada")

    // Serialize: object -> JSON String
    val json = mapper.writeValueAsString(user)
    println(json) // {"id":1,"name":"Ada","active":true}

    // Deserialize: JSON String -> typed object
    val parsed: User = mapper.readValue(json)
    println(parsed) // User(id=1, name=Ada, active=true)
}

import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
import com.fasterxml.jackson.module.kotlin.readValue

data class Product(val sku: String, val price: Double)

val mapper = jacksonObjectMapper()

fun main() {
    val jsonArray = """[{"sku":"A1","price":9.99},{"sku":"B2","price":19.5}]"""

    // Without reified types, the element type would be erased.
    val products: List<Product> = mapper.readValue(jsonArray)
    println(products.size)        // 2
    println(products.first().sku) // A1
}

import com.fasterxml.jackson.databind.DeserializationFeature
import com.fasterxml.jackson.databind.SerializationFeature
import com.fasterxml.jackson.databind.json.JsonMapper
import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule
import com.fasterxml.jackson.module.kotlin.kotlinModule

val mapper = JsonMapper.builder()
    .addModule(kotlinModule())   // Kotlin data-class support
    .addModule(JavaTimeModule()) // Instant/LocalDate as ISO-8601, not epoch numbers
    .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
    .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false)
    .build()

import com.fasterxml.jackson.databind.DeserializationFeature
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.bind.annotation.*

data class CreateUserRequest(val name: String, val email: String)

@RestController
@RequestMapping("/users")
class UserController {
    @PostMapping
    fun create(@RequestBody body: CreateUserRequest): String =
        "Created " + body.name // Spring deserializes JSON into the data class for you
}

@Configuration
class JacksonConfig {
    @Bean
    fun kotlinCustomizer() = Jackson2ObjectMapperBuilderCustomizer { b ->
        b.featuresToDisable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
    }
}