/scala-json-survey

A survey of Scala JSON ecosystem

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