Working with JSON in Kotlin: Parsing and Serialization for Beginners

Introduction: Why Kotlin Works with JSON?

JSON (JavaScript Object Notation) is a lightweight data interchange format that has become the standard for modern web applications and APIs. If you write in Kotlin, whether it's an Android app or a server-side component, sooner or later you will need to parse JSON responses from a server or serialize your objects for sending.

Kotlin is a modern language that runs on top of the JVM and is fully compatible with Java. However, Kotlin has its own powerful tools for working with JSON that make code more concise and safe. In this article, we will cover two of the most popular approaches: using the official kotlinx.serialization library and the time-tested Gson.

This article is aimed at beginners. We will start with simple string parsing, then move on to creating complex nested structures, and finally touch on serialization — converting your objects back to JSON.

1. Project Setup: Dependencies and Imports

Before writing code, you need to add the libraries. We will cover two options.

1.1. Installing kotlinx.serialization

This is the official solution from JetBrains. Add the following to your build.gradle.kts file:

plugins {\n    kotlin("jvm") version "1.9.0"\n    kotlin("plugin.serialization") version "1.9.0"\n}\n\ndependencies {\n    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.0")\n}\n

1.2. Installing Gson

Gson is a library from Google. It is simpler to set up but requires more manual work:

dependencies {\n    implementation("com.google.code.gson:gson:2.10.1")\n}\n

After syncing the project, you can start writing code.

2. Parsing JSON in Kotlin with kotlinx.serialization

This approach is the most "Kotlin-esque". You declare data classes and add the @Serializable annotation. The library will generate the parsing code itself.

2.1. Simple Example: User Data

Suppose we have a JSON string:

{\n    "name": "Anna",\n    "age": 25,\n    "email": "anna@example.com"\n}\n

Create the model:

import kotlinx.serialization.Serializable\nimport kotlinx.serialization.json.Json\n\n@Serializable\ndata class User(\n    val name: String,\n    val age: Int,\n    val email: String\n)\n\nfun main() {\n    val jsonString = """\n        {\n            "name": "Anna",\n            "age": 25,\n            "email": "anna@example.com"\n        }\n    """.trimIndent()\n\n    val user = Json.decodeFromString<User>(jsonString)\n    println("Name: ${user.name}, Age: ${user.age}")\n}\n

As you can see, no manual mappings — everything is automatic.

2.2. Working with Lists and Nested Objects

Real APIs often return arrays. Let's add an address field:

@Serializable\ndata class Address(\n    val city: String,\n    val street: String\n)\n\n@Serializable\ndata class UserWithAddress(\n    val name: String,\n    val age: Int,\n    val address: Address\n)\n\nfun main() {\n    val jsonArray = """\n        [\n            {"name": "Ivan", "age": 30, "address": {"city": "Moscow", "street": "Tverskaya"}},\n            {"name": "Maria", "age": 22, "address": {"city": "SPb", "street": "Nevsky"}}\n        ]\n    """.trimIndent()\n\n    val users = Json.decodeFromString<List<UserWithAddress>>(jsonArray)\n    users.forEach { println("${it.name} lives in ${it.address.city}") }\n}\n

Note: to work with lists, the generic List<UserWithAddress> is used.

3. Parsing JSON with Gson

Gson is a classic Java library. It also works great in Kotlin, but requires a bit more code.

3.1. Basic Parsing

import com.google.gson.Gson\n\ndata cl