givesocialmovement / play-json-form

JSON form submission and validation for Playframework

Version Matrix

JSON Form for Playframework

CircleCI codecov Gitter chat

This is a replacement of Play's form submission and validation.

The library is inherently compatible with JSON, as in the conversion between JsValue and a case class is symmetric. In contrast, The standard Play's form library doesn't hold the symmetry property when converting nested objects and arrays.

But why is JSON compatibility important?

At, we serialize to json and pass it to a Vue component.

Since didn't support converting to JSON, we converted its member data: Map[String, String] to JSON instead.

With Map[String, String], a JSON { "images": ["test.png"] } would eventually be converted to { "images[0]": "test.png" }. And it became tricky to modify our Vue components to handle this kind of array encoding.

Please note that converting JSON into case class (using bindFromRequest) works fine. In a rare occasion that you might have a field that contains [..], that might cause an issue.

Please see this blog post, which also explains how we build a form, for more context:

Why can't we modify to be fully compatible with JSON?

Map[String, String] isn't powerful enough to support JsObject, and it is defined in many critical places. For example, Mapping.unbind returns Map[String, String].

Since JsObject is powerful enough to support Map[String, String], one good way to improve Play's form with backward compatibility is to make Mapping.unbind return JsObject and provides a thin layer that converts JsObject to Map[String, String].

Advanced and experimental features

List all possible validation errors

At, we have more than 20 forms, each of which has several fields. It's tedious to ensure every error message is translated. Previously, what we did is to writing tests on controllers where we send requests with invalid input. It was odd to test the whole path of HTTP request in order to verify that our error messages are translated. So, we've come up with a new way of ensuring every error message is translated.

Form.getAllErrors() conveniently generates all possible validation errors. However, when building a Mapping, we need to properly code all the possible validation errors. For example:

new Mapping[String] {

  def bind(value: JsLookupResult, context: BindContext): Try[String] = {
    // Do something
  def unbind(value: String, context: UnbindContext): JsValue = {
    // Do something

The work is still tedious but much less tedious than without one. We are open to hear about a better design.

Map a value that depends on another value

At, we have the use case where we want to convert an amount from String (as in 1,000.53 or 1,000) to cents, which is Long. However, we can't convert it unless we know the currency first. Because, for a two-decimal currency, we will multiply the value by 100. But, for a zero-decimal currency, we won't. It follows the guideline by Stripe.

One simple solution is to make 2 forms. The first form processes the currency. Then, we use the currency to create the second form. That's clunky.

Our solution is that we offer BindContext which allows Mapping to access its context, or, in other words, the values of its peers. For example:

new Mapping[String] {
  def bind(value: JsLookupResult, context: BindContext): Try[Long] = {
    context.get("currency") match {
      case Some(currency: Currency) =>
        if (currency.isZeroDecimal) {
        } else {
      // The currency field might fail to be parsed. In this case, this mapping is not applicable.
      case _ => Failure(NotApplicationException) 
  def unbind(value: String, context: UnbindContext): JsValue = {
    // Do something

The design is a little awkward. But it hides complexity from the user. We are open to hear about a better design.

Important compatibility notes

Since we aim to facilitate the migration from Play's Form, there are certain counter-intuitive behaviours that should be highlighted.

The below are the behaviours that you need to enable explicitly:

  • Set coerceToString to true in order to make text convert any type (e.g. JsNumber) to String.
  • Set translateNoneToEmpty to true in order to make seq accept the absence of the value as Seq.empty ref.
  • Set translateEmptyStringToNone to true in order to make opt(text) translate an empty string to None ref.
  • Set translateAbsenceToFalse to true in order to make boolean translate the absence of the key as false ref.

When migrating from Play's Form, you should enable all of these flags to avoid surprises.

The below behaviours are enabled automatically because they are sensible. Here they are:

  • number and longNumber accept both JsString and JsNumber.
  • boolean accepts both JsString and JsBoolean.

Most of these behaviours stem from the fact that JsObject has more complex types while Map[String, String] doesn't.


Add the below line to your build.sbt:

resolvers += Resolver.bintrayRepo("givers", "maven")

libraryDependencies += "givers.form" %% "play-json-form" % "1.0.0"

The artifacts are hosted here:


You can see a fully working example in the folder example-project.

Making a form:

import givers.form.Form
import givers.form.Mappings._

case class Obj(a: String, b: Int)

val form = Form(
    "a" -> text(allowEmpty = false),
    "b" -> number()

// We also have a slightly shorter API:
val form2 = Form(
  "a" -> text(allowEmpty = false),
  "b" -> number()


Building a Mapping based on another Mapping:

import givers.form.Mappings

object Currency extends Enumeration {
  val SGD, USD, EUR = Value

val currency = Mappings.text(allowEmpty = false).transform[Currency.Value](
  bind = { s =>
    try {
    } catch {
      case _: Exception => Failure(Mapping.error("error.invalid", s))
  unbind = _.toString

Extend a Mapping with an additional validation:

import givers.form.Mappings

val email = Mappings.text.validate("") { s => s.nonEmpty && s.contains("@") }

Please see all predefined mappings in givers.form.Mappings.


  1. Run sbt generator/run in order to generate the classes in givers.form.generated.
  2. Run sbt test to run all tests