Advanced topics

Tutorials

Books

The Play JSON library

Overview

The recommend way of dealing with JSON is using Play’s typeclass based JSON library, located at play.api.libs.json.

This library is built on top of Jerkson, which is a Scala wrapper around the super-fast Java based JSON library, Jackson.

The benefit of this approach is that both the Java and the Scala side of Play can share the same underlying library (Jackson), while Scala users can enjoy the extra type safety that Play’s JSON support brings to the table.

play.api.libs.json package contains seven JSON data types:

JsObject

JsNull

JsUndefined

JsBoolean

JsNumber

JsArray

JsString

All of them inherit from the generic JSON value, JsValue.

Parsing a Json String

You can easily parse any JSON string as a JsValue:

val json: JsValue = Json.parse(jsonString)

Navigating into a Json tree

As soon as you have a JsValue you can navigate into the tree. The API looks like the one provided to navigate into XML document by Scala using NodeSeq:

Note that navigating using \ and \ never fails. You must handle the error case at the end using asOpt[T] that will return None if the value is missing. Otherwiser you can use as[T] that we fail with an exception if the value was missing.

Converting a Scala value to Json

As soon as you have a type class able to transform the Scala type to Json, it is pretty easy to generate any Scala value to Json. For example let’s create a simple Json object:

val jsonNumber = Json.toJson(4)

Or create a json array:

val jsonArray = Json.toJson(Seq(1, 2, 3, 4))

Here we have no problem to convert a Seq[Int] into a Json array. However it is more complicated if the Seq contains heterogeous values:

val jsonArray = Json.toJson(Seq(1, "Bob", 3, 4))

Because there is no way to convert a Seq[Any] to Json (Any could be anything including something not supported by Json right?)