Functional style JSON parsing written in Kotlin
Switch branches/tags
Nothing to show
Clone or download


Kotlin jcenter 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.




repositories {

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": "",
  "friends": [
        "id": 11,
        "name": "Ervin Howell",
        "age": 32,
        "email": "",
        "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 friends: List<User>,
                val dogs: List<Dog>?)

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(json.list("friends", ::userDeserializer)).  //userDeserializer is a function, use :: as a function reference
        apply(json.maybeList("dogs", dogDeserializer))  //dogDeserializer is a lambda, use it directly

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