A survey of Scala JSON ecosystem
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


JSON survey

This project aims to provide a comprehensive summary of JSON libraries in Scala:

  1. Basic features: the essentials for working with JSON, mapping it to/from case classes, etc.
  2. Library support: which base libraries are supported by various projects in the wild.
  3. Links and resources: further reading.

Basic features

In this section we explore the essentials for working with JSON:

  • Simple JSON construction — an easy way to construct the JSON tree.
    • DSL — something like ("name" -> "joe") ~ ("age" -> 35) (json4s);
    • interpolator — something like json"""{name: "joe", age: 35}""" (jsonquote).
  • Codecs — how data (mostly case classes) is converted to JSON.
    • typeclass-based — a more flexible approach, checked at compile-time;
    • reflection-based — somewhat non-idiomatic, not checked at compile-time.
  • Automatic codec derivation — whether manual labor is required to convert case classes and sealed traits into JSON.
    • macro-based — fast, but typically somewhat ad-hoc and lacking support for sealed traits, multiple apply methods in the companions, etc;
    • shapeless-based — might take more time to compile, but provides robust support for arbitrary case classes and sealed traits.
  • Immutable manipulation — an easy way to manipulate JSON, modify, remove fields, etc. (You can learn more about lenses and zippers from my talk!)
    • zipper-based — something like (cursor --\ "outerKey" --\ "innerkey2").withFocus(_.withString(_ + "!")) (argonaut);
    • lens-based — something like json.updateAs[String](__ \ "outerKey" \ "innerkey2", _ + "!") (play-json-zipper — contrary to what the name suggests).
  • Diff & patch — diffing and patching JSON along the lines of RFC 6902.
  • JSON Schema — validing JSON against a schema along the lines of RFC ???.
Base library Simple JSON construction Codecs Automatic codec derivation Immutable manipulation Diff & patch JSON Schema
Argonaut included DSL typeclass-based included, macro-based; shapeless-based included, zipper-based yes ?
Circe ? typeclass-based included, shapeless-based included, zipper-based no ?
json4s included DSL reflection-based included, reflection-based included, path-based included ?
Play JSON included; interpolator-based typeclass-based included, macro-based; shapeless-based lens-based yes yes
Spray JSON interpolator-based typeclass-based included, reflection-based; shapeless-based lens-based yes ?

Library support

This section outlines the support for the above base libraries in the wild.

Project/topic Argonaut Circe json4s Play JSON Spray JSON
Akka HTTP yes yes yes yes yes
JWT ? yes yes yes yes
Slick Postgres yes yes yes yes yes
GeoJSON yes ? ? yes yes

Links and resources