Almost every Android app talks to an API, and almost every API returns JSON. Writing Kotlin data classes by hand for a large response is slow and error-prone – one wrong type and the app crashes on parse. This guide explains how JSON maps to Kotlin, which library annotations you need and how to generate the classes automatically.
Page Contents
How JSON types map to Kotlin
| JSON | Kotlin |
|---|---|
| “text” | String |
| 42 | Int (or Long for big numbers) |
| 4.5 | Double |
| true / false | Boolean |
| { … } | A nested data class |
| [ … ] | List of a type |
| null | A nullable type, for example String? |
A simple example
For a JSON user object with id, name, email, an address object and a list of tags, you get:
data class User(val id: Int, val name: String, val email: String?, val address: Address, val tags: List<String>)data class Address(val city: String, val zip: String)
Choose your library
kotlinx.serialization (recommended for new Kotlin projects)
Add @Serializable to each class and @SerialName("user_name") when the JSON key differs from your property name. It is Kotlin-first, works with Kotlin Multiplatform and does not use reflection.
Gson
Widely used in older projects. Use @SerializedName("user_name"). Be careful: Gson can put null into non-null Kotlin properties when a field is missing, which causes crashes later.
Moshi
A modern alternative that understands Kotlin nullability. Use @Json(name = "user_name") with the Kotlin codegen adapter.
Nullable or not?
The most common crash comes from declaring a property as non-null when the API sometimes omits it or sends null. Rules of thumb:
- If a field can be missing or null in any response, make it nullable (
String?) or give it a default value (val bio: String = ""). - Generate classes from several real responses, not just one.
- Optional numbers often appear as
null– useInt?.
Naming: snake_case to camelCase
APIs often use created_at, while Kotlin style is createdAt. Keep Kotlin names in camelCase and map them with @SerialName, @SerializedName or @Json. Our Case Converter helps with quick renames.
Generate classes automatically
- Copy a real API response (format it first with our JSON Formatter if it is minified).
- Paste it into the JSON to Kotlin converter.
- Choose the library and the root class name.
- Copy the classes into your project and review nullability.
Common parsing errors
- “Expected BEGIN_OBJECT but was BEGIN_ARRAY” – the JSON is a list, but you parsed it as a single object. Use
List<User>. - “Field ‘x’ is required but it was missing” (kotlinx) – make it nullable or give it a default.
- “Unexpected JSON token” – the response is not valid JSON, often an HTML error page.
- Number format errors – the API sends numbers as strings (“42”). Use String or a custom serializer.
FAQ
What is a data class in Kotlin?
A class meant to hold data. Kotlin generates equals, hashCode, toString and copy automatically.
Which JSON library should I use on Android?
kotlinx.serialization for new Kotlin projects; Moshi is also a strong choice. Gson is common in older code.
How do I handle JSON keys with different names?
Use @SerialName, @SerializedName or @Json to map the JSON key to a Kotlin property.
How do I parse a JSON array?
Parse it into List of your data class, for example List of User.
Is my JSON sent anywhere?
No. Our converter runs entirely in your browser.
Need help building or publishing your app? Talk to Techpass Master – we design, build and publish Android apps for clients worldwide.
