Skip to content
Switch branches/tags
Go to file


Failed to load latest commit information.
Latest commit message
Commit time


Kotlin jcenter MavenCentral Build Status Codecov

Forge is a JSON parsing library that helps you map your Kotlin class from a JSON in a functional way. Forge is highly inspired by Aeson, JSON parsing library in Haskell.


Have you ever wonder that how other JSON libraries out there work? Magic under the hood? or a complex annnotation processing? If that is something that you don't want, with Forge, we don't do any of those.

Forge aims to provide a full control over how to parse JSON into a Kotlin class, no more magic, no more annotation.



repositories {
    jcenter() //or mavenCentral()

dependencies {
    compile 'com.github.kittinunf.forge:forge:<latest-version>'

Usage (tl;dr:)

Given you have JSON as such

  "id": 1,
  "name": "Clementina DuBuque",
  "age": 46,
  "email": "",
  "phone": {
    "name": "My Phone",
    "model": "Pixel 3XL"
  "friends": [
        "id": 11,
        "name": "Ervin Howell",
        "age": 32,
        "email": "",
        "phone": {
            "name": "My iPhone",
            "model": "iPhone X"
        "friends": []
  "dogs": [
      "name": "Lucy",
      "breed": "Dachshund",
      "is_male": false

You can write your Kotlin class definition as such

data class User(val id: Int,
                val name: String,
                val age: Int,
                val email: String?,
                val phone: Phone,
                val friends: List<User>,
                val dogs: List<Dog>?)

data class Phone(val name: String, val model: String)
data class Dog(val name: String, val breed: String, val male: Boolean)

fun userDeserializer(json: JSON) =
        map(json at "id").
        apply(json at "name").
        apply(json at "age").
        apply(json maybeAt "email").
        apply("phone", phoneDeserializer)),  // phoneDeserializer is a lambda, use it directly
        apply(json.list("friends", ::userDeserializer)).  //userDeserializer is a function, use :: as a function reference
        apply(json.maybeList("dogs", dogDeserializer))

val phoneDeserializer = { json: JSON ->
        map(json at "name").
        apply(json at "model")

val dogDeserializer = { json: JSON ->
        map(json at "name").
        apply(json at "breed").
        apply(json at "is_male")

Viola!, then, you can deserialize your JSON like

//jsonContent is when you receive data as a JSON
val result = Forge.modelFromJson(jsonContent, ::userDeserializer)

when (result) {
    DeserializedResult.Success -> {
        val user = result.value
        //success, do something with user

    DeserializedResult.Failure -> {
        val error = result.error
        //failure, do something with error


Forge is brought to you by contributors.


Forge is released under the MIT license.