Awesome
(Note: this project has been renamed from play-json-variants to play-json-derived-codecs
)
Play JSON Derived Codecs ![](https://index.scala-lang.org/julienrf/play-json-derived-codecs/play-json-derived-codecs/latest.svg)
Reads
, OWrites
and OFormat
derivation for algebraic data types (sealed traits and case classes, possibly recursive), powered by shapeless.
Compared to the built-in macros, this project brings support for:
- sealed traits ;
- recursive types ;
- polymorphic types.
The artifacts are built for Scala and Scala.js 2.12, and 2.13, Play 3.0 and Shapeless 2.3.
Versions
For previous versions of Play, you can use previous versions of this library:
Library version | Play version |
---|---|
Latest | 3.0.x |
10.1.0 | 2.9.x |
7.0.0 | 2.8.x |
Usage
import julienrf.json.derived
case class User(name: String, age: Int)
object User {
implicit val reads: Reads[User] = derived.reads()
}
The API is simple: the object
julienrf.json.derived
has just three methods.
reads[A]()
, derives aReads[A]
;owrites[A]()
, derives aOWrites[A]
;oformat[A]()
, derives aOFormat[A]
.
Representation of Sum Types
By default, sum types (types extending a sealed trait) are represented by a JSON object containing one field whose name is the name of the concrete type and whose value is the JSON object containing the value of the given type.
For instance, consider the following data type:
sealed trait Foo
case class Bar(s: String, i: Int) extends Foo
case object Baz extends Foo
The default JSON representation of Bar("quux", 42)
is the following JSON object:
{
"Bar": {
"s": "quux",
"i": 42
}
}
Configuring the Derivation Process
Three aspects of the derivation process can be configured:
- the representation of sum types,
- the way case class field names are mapped to JSON property names,
- the type name used to discriminate sum types.
Custom Representation of Sum Types
The default representation of sum types may not fit all use cases. For instance, it is not very practical for enumerations.
For instance, you might want to represent the Bar("quux", 42)
value as the following JSON object:
{
"type": "Bar",
"s": "quux",
"i": 42
}
Here, the type information is flattened with the Bar
members.
You can do so by using the methods in the derived.flat
object:
implicit val fooOWrites: OWrites[Foo] =
derived.flat.owrites((__ \ "type").write[String])
In case you need even more control, you can implement your own TypeTagOWrites
and TypeTagReads
.
Custom Field Names Mapping
By default, case class fields are mapped to JSON object properties having the same name.
You can transform this mapping by supplying a different NameAdapter
parameter. For
instance, to use “snake case” in JSON:
implicit val userFormat: OFormat[User] = derived.oformat(adapter = NameAdapter.snakeCase)
Custom Type Names
By default, case class names are used as discriminators (type tags) for sum types.
You can configure the type tags to use by using the derived.withTypeTag
object:
implicit val fooFormat: OFormat[Foo] =
derived.withTypeTag.oformat(TypeTagSetting.FullClassName)
The library provides the following TypeTagSetting
values out of the box:
TypeTagSetting.ShortClassName
: use the class name (as it is defined in Scala)TypeTagSetting.FullClassName
: use the fully qualified nameTypeTagSetting.UserDefinedName
: require the presence of an implicitCustomTypeTag[A]
for all typeA
of the sum type, providing the type tag to use
Custom format for certain types in hierarchy
Sometimes, you might want to represent one type differently than default format would. This can be done by creating an implicit instance of DerivedReads
or DerivedWrites
for said type. Below is an example of implementing both custom reads and writes for a single class in a hierarchy:
sealed trait Hierarchy
case class First(x: Integer)
case class Second(y: Integer)
implicit val SecondReads: DerivedReads[Second] = new DerivedReads[Second] {
def reads(tagReads: TypeTagReads, adapter: NameAdapter) = tagReads.reads("Second", (__ \ "foo").read[Integer].map(foo => Second(foo)))
}
implicit val SecondWrites: DerivedOWrites[Second] = new DerivedOWrites[Second] {
override def owrites(tagOwrites: TypeTagOWrites, adapter: NameAdapter): OWrites[Second] =
tagOwrites.owrites[Second](
"Second",
OWrites[Second](s => JsObject(("foo", Json.toJson(s.y)) :: Nil))
)
}
val defaultTypeFormat = (__ \ "type").format[String]
implicit val HierarchyFormat = derived.flat.oformat[Hierarchy](defaultTypeFormat)
This will cause Second
to be read with SecondReads
, and read with SecondWrites
.
Avoiding redundant derivation
By default, the auto-derivation mechanism will be applied to the whole sealed hierarchy. This might be costly in terms of compile-time (as Shapeless is being used under the hood).
To avoid this, it is possible to define an Format
for the different cases, thus only using auto-derivation for the branching in the sealed trait and nothing else.
sealed trait Hierarchy
case class First(a: Int, b: Int, c: Int) extends Hierarchy
case class Second(x: Int, y: Int, c: Int) extends Hierarchy
object First {
implicit val format: OFormat[First] = Json.format
}
object Second {
implicit val format: OFormat[Second] = Json.format
}
implicit val HierarchyFormat = derived.oformat[Hierarchy]()
Important note: in case derived.flat
is being used, it's recommended that the provided Format
s actually produce JsObject
s. If that's not the case, a synthetic wrapper around the user-provided result will be generated on-the-fly.
For this reason, Json.valueFormat
and the like are not compatible with derived.flat
, and it is best to avoid using them together.
Here is what will happen if they are used together:
sealed trait Foo
case class Bar(x: Int) extends Foo
object Bar {
implicit val format: Format[Bar] = Json.valueFormat
}
implicit val fooFormat = derived.flat.oformat[Foo]((__ \ "type").format[String])
Json.toJson(Bar(42)) // { "type": "Bar", "__syntheticWrap__": 42 }
Without the provided Format
s the derivation mechanism will traverse all the fields in the hierarchy (in this case 6 in total), which may be costly for larger case classes.
Providing the implicits this way can also be used for customization without having to deal with supplying your own type-tags.
Contributors
See here.
Changelog
See here.