How to Convert JSON to Kotlin Data Classes (Gson, Moshi, kotlinx.serialization)

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.

Free tool
Convert JSON to Kotlin
Paste JSON and get Kotlin data classes with nested classes, lists, nullable types and kotlinx.serialization, Gson or Moshi annotations. Free – nothing uploaded.
Open JSON to Kotlin →

How JSON types map to Kotlin

JSONKotlin
“text”String
42Int (or Long for big numbers)
4.5Double
true / falseBoolean
{ … }A nested data class
[ … ]List of a type
nullA 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 – use Int?.

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.

Free tool
Try the free JSON to Kotlin
No signup and nothing uploaded – it runs right in your browser. Browse all 74 free tools on our Free Tools page.
Open JSON to Kotlin →

Need help building or publishing your app? Talk to Techpass Master – we design, build and publish Android apps for clients worldwide.

WhatsApp us📞 Call now