Working with JSON

  • how-to
    The SDK makes it easy to turn Kotlin objects into JSON, and JSON into Kotlin objects.

    Before You Start

    You should know about JSON.

    Introduction to Data Binding

    It’s good to store documents in JSON format, because some Couchbase services only work with JSON documents.

    When we talk about "data binding" in the Couchbase SDK, we mean converting Kotlin objects into JSON, and converting JSON into Kotlin objects. Data binding happens automatically, so you don’t need to write a lot of code.

    Data binding with Map

    The simplest data binding uses a Kotlin Map object to represent document content. Here is an example:

    Using a Kotlin Map to represent document content
        id = "alice",
        content = mapOf("favoriteColor" to "blue"),
    val result: GetResult = collection.get("alice")
    println("Content in Couchbase: " + String(result.content.bytes))
    println("Content as Map: " + result.contentAs<Map<String, Any?>>())

    The example prints:

    Content in Couchbase: {"favoriteColor":"blue"} (1)
    Content as Map: {favoriteColor=blue} (2)
    1 The SDK converted the Map to JSON, then saved the JSON in Couchbase.
    2 The contentAs method converted the JSON into a Kotlin Map.

    Data binding with your own classes

    It’s often good to make Kotlin classes that represent the structure of your data. Then you can work your own classes instead of maps.

    When you write a document, the content argument can be an instance of your own class. The SDK uses data binding to convert your object to JSON.

    When you read a document, you can ask the SDK to convert the content to an instance of your own class.

    Here is an example:

    Data binding with a user-defined class
    data class MyClass(
        val favoriteColor: String,
        id = "alice",
        content = MyClass(favoriteColor = "blue"),
    val result: GetResult = collection.get("alice")
    println("Content in Couchbase: " + String(result.content.bytes))
    println("Content as MyClass: " + result.contentAs<MyClass>())

    The example prints:

    Content in Couchbase: {"favoriteColor":"blue"}
    Content as MyClass: MyClass(favoriteColor=blue)

    In this example, MyClass is very simple — it has only one property. Data binding works with complicated classes, too. Your classes can have properties that are maps or lists of other complicated objects. Experiment and have fun!

    Writing content already in JSON format

    If the data you want to save in Couchbase is already in JSON format, you must tell the SDK to skip data binding.

    There are two ways to skip data binding. This example shows both ways:

    Writing a JSON document without data binding
    val jsonContent = """{"favoriteColor":"blue"}"""
    // Option A
        id = "alice",
        content = jsonContent,
        transcoder = RawJsonTranscoder, (1)
    // Option B
        id = "alice",
        content = Content.json(jsonContent), (1)
    1 We will talk more about RawJsonTranscoder and Content in the transcoders section.

    If you use a String for the content when changing a document, and don’t skip data binding, the SDK assumes you want the document content to be a JSON String. For example, if you write:

    // Don't do this!
        id = "alice",
        content = """{"favoriteColor":"blue"}"""

    The document content in Couchbase is:


    instead of what you probably want:


    To fix this problem, skip data binding,

    Reading JSON content without data binding

    Sometimes it’s useful to get the content of a JSON document as a byte array. This examples shows how to get the unprocessed bytes of a document:

    Reading a JSON document as a byte array
    val result: GetResult = collection.get(id = "alice")
    val jsonBytes: ByteArray = result.content.bytes (1)
    1 The byte array contains the unprocessed document content. You can parse the JSON yourself, or do something else with the bytes.


    The part of the SDK that does data binding is called a JsonSerializer. The SDK includes serializers for some popular JSON libraries. You can add support for other libraries, too.


    The Kotlin SDK uses the Jackson data binding library. Jackson is a fast and popular library for working with JSON.

    The Kotlin SDK includes a repackaged version of Jackson for its own internal use. Your code should not use that version of Jackson. Always import Jackson classes from the com.fasterxml.jackson package. Never import Jackson classes from the package.

    When you use your own classes for data binding, you can put special Jackson annotations on your classes to change how the data binding works. You can use annotations to change the JSON field names, or ignore some properties of your classes. Jackson is a powerful tool with many features.

    To learn more about Jackson, please read the Jackson documentation.

    Jackson Tree Model

    Jackson can represent a JSON document as a tree of JsonNode objects. You can use data binding with JsonNode. This is useful if you don’t know the structure of the document. For example:

    val json = collection.get(id = "alice").contentAs<JsonNode>()
    when {
        json is ArrayNode -> println("Content is a JSON Array")
        json is ObjectNode -> println("Content is a JSON Object")
        else -> println("Content is a JSON primitive")

    Sometimes it’s easier to do data binding with a JsonNode than a Map.

    Customizing the Jackson mapper

    By default, JacksonJsonSerializer uses a JsonMapper with default settings, and the Kotlin and JDK 8 modules.

    You can use your own Jackson mapper instead. This example creates a JacksonJsonSerializer with a different mapper, and configures the SDK to use it by default:

    Overriding the default Jackson JsonMapper
    val jsonMapper: JsonMapper = getMyCustomJsonMapper()
    val cluster = Cluster.connect(connectionString, username, password) {
        jsonSerializer = JacksonJsonSerializer(jsonMapper)


    Moshi is another popular library for working with JSON. If you like Moshi more than Jackson, you can tell the SDK to use Moshi instead.

    First, add Moshi as a dependency of your project:

    • Gradle (Kotlin)

    • Gradle (Groovy)

    • Maven

    implementation "com.squareup.moshi:moshi-kotlin:1.13.0"

    When you connect to the cluster, tell the SDK to use Moshi as the default JSON serializer:

    val moshi = Moshi.Builder()
    val cluster = Cluster.connect(connectionString, username, password) {
        jsonSerializer = MoshiJsonSerializer(moshi) (1)
    1 Please read the MoshiJsonSerializer API reference to see more options.

    Custom JsonSerializer

    If there is a JSON library you like more than Jackson or Moshi, you can make your own serializer by implementing the JsonSerializer interface. The Moshi section shows how to tell the SDK which serializer to use.

    Alternatively, you can skip data binding and use your preferred JSON library to read and write JSON without using the SDK.