You are viewing the documentation for the 2.5.0 release in the 2.5.x series of releases. The latest stable release series is 3.0.x.

§JSON automated mapping

If the JSON maps directly to a class, we provide a handy macro so that you don’t have to write the Reads[T], Writes[T], or Format[T] manually. Given the following case class :

case class Resident(name: String, age: Int, role: Option[String])

The following macro will create a Reads[Resident] based on its structure and the name of its fields :

import play.api.libs.json._

implicit val residentReads = Json.reads[Resident]

When compiling, the macro will inspect the given class and
inject the following code, exactly as if you had written it manually :

import play.api.libs.json._
import play.api.libs.functional.syntax._

implicit val residentReads = (
  (__ \ "name").read[String] and
  (__ \ "age").read[Int] and
  (__ \ "role").readNullable[String]
)(Resident)

This is done at compile-time, so you don’t lose any type safety or performance.
Similar macros exists for a Writes[T] or a Format[T] :

import play.api.libs.json._

implicit val residentWrites = Json.writes[Resident]

import play.api.libs.json._

implicit val residentFormat = Json.format[Resident]

§Requirements

These macros rely on a few assumptions about the type they’re working with :
- It must have a companion object having apply and unapply methods
- The return types of the unapply must match the argument types of the apply method.
- The parameter names of the apply method must be the same as the property names desired in the JSON.

Case classes natively meet these requirements. For more custom classes or traits, you might
have to implement them.

Next: JSON Transformers