JSON4S

今現在 java json ライブラリを含めないで少なくとも 6つの scala向け json ライブラリがあります。

すべてのそれらのライブラリは非常に似たASTを持っています。このプロジェクトでは他のscala json ライブラリで使用されるただひとつのASTを提供することを目指しています。

今現在 lift-json 由来の AST を使用するアプローチを取っており、 native パッケージは事実 lift-json ですが、しかし lift プロジェクトの外部プロジェクトです。

Lift JSON

このプロジェクトは lift-json に lift フレームワークより課されてたリリーススケジュールから開放することを試みます。

Lift フレームワークは多くの依存関係を含んでおり、それらは新しい scala のバージョンがリリースされた時にたいてい、多くの他 scala プロジェクトへの妨げるになる。

このライブラリの native パッケージは実際文字通り違うパッケージ名の lift-json である。これはこのライブラリを使う場合インポートステートメントが変わることを意味します。

import org.json4s._
import org.json4s.native.JsonMethods._

あとはすべて lift-json と全く同じように動作する。

Jackson

native パーサーに加えて ASTをパースするのに jackson を使った実装もあります。

jackson モジュールはほとんどの jackson-module-scala 機能を含んでおり、 lift-json AST を共に使用することができる。

native パーサーに代わって jackson を使うには

import org.json4s._
import org.json4s.jackson.JsonMethods._

jackson 統合のデフォルトの動作ではストリームが完了するとそれがクローズされる動作となることをご留意ください。
もし変更したい場合には：

import com.fasterxml.jackson.databind.SerializationFeature
org.json4s.jackson.JsonMethods.mapper.configure(SerializationFeature.CLOSE_CLOSEABLE, false)

ガイド

JSON の分析とフォーマットをするためのユーティリティ

lift-json ライブラリの中心となる概念は、構文木として JSONドキュメント構造モデル化した Json AST である。

sealed abstract class JValue
case object JNothing extends JValue // 'zero' for JValue
case object JNull extends JValue
case class JString(s: String) extends JValue
case class JDouble(num: Double) extends JValue
case class JDecimal(num: BigDecimal) extends JValue
case class JInt(num: BigInt) extends JValue
case class JBool(value: Boolean) extends JValue
case class JObject(obj: List[JField]) extends JValue
case class JArray(arr: List[JValue]) extends JValue

type JField = (String, JValue)

すべての機能は上記 AST の用語で実現されている。機能は AST それ自体の変更、あるいは AST と違うフォーマット間の変換に使用される。一般的な変換は以下の図に要約される。

機能概要:

高速な JSON 解析
LINQ スタイルのクエリ
解析された JSON から値を抽出するのに case class を使うことができる。
差分と結合
有効なJSONを生成するDSL
XPath ライクな式と JSON を操作する HOFs
コンパクトに整えられた出力形式
XML 変換
シリアル化
低レベル pull parser API

インストール

以下の方法で json4s の依存関係を追加できます。
注: {latestVersion} を適切な Json4s のバージョンに置き換えてください。

入手可能なバージョンはこちらから見つけることが出来ます。: http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.json4s%22

SBT ユーザ

native を使用する場合以下の依存関係をプロジェクトの description に追加してください:

val json4sNative = "org.json4s" %% "json4s-native" % "{latestVersion}"

Jackson を使用する場合以下の依存関係をプロジェクトの description に追加してください:

val json4sJackson = "org.json4s" %% "json4s-jackson" % "{latestVersion}"

Maven ユーザ

native を使用する場合、以下の依存関係を pom に追加してください:

<dependency>
  <groupId>org.json4s</groupId>
  <artifactId>json4s-native_${scala.version}</artifactId>
  <version>{latestVersion}</version>
</dependency>

jackson を使用する場合、以下の依存関係を pom に追加してください:

<dependency>
  <groupId>org.json4s</groupId>
  <artifactId>json4s-jackson_${scala.version}</artifactId>
  <version>{latestVersion}</version>
</dependency>

追加

Enum, Joda-Time,… のサポート

scalaz

Scalaz によるアプリカティブスタイル解析

native-lift

Box のサポート

旧バージョンからの移行

3.3.0 ->

json4s 3.3 は基本的には 3.2.x とソースコード互換であるべきです。 json4s 3.3.0 以降我々はここに記載のあるバイナリ互換性の問題を繰り返さない為にバイナリ互換性の確認の為に MiMa を使い始めました。

JValueの .toOption の動作が変更されました。現在は JNothing と JNull の両方が None を返します。以前の動作の為には JNothing だけが None になる toSome を使えます。

すべてのマージされたプルリクエスト: https://github.com/json4s/json4s/pulls?q=is%3Apr+is%3Aclosed+milestone%3A3.3

3.0.0 ->

JField はもはや JValue ではありません。これはさらに型安全であることを意味し、インスタンスのために直接的にJArrayに加えられたJFieldの不正なJSONの生成はもはや可能ではない。この変更のもっとも大きな影響は 2種類の map、transform、find、filter です:

def map(f: JValue => JValue): JValue
def mapField(f: JField => JField): JValue
def transform(f: PartialFunction[JValue, JValue]): JValue
def transformField(f: PartialFunction[JField, JField]): JValue
def find(p: JValue => Boolean): Option[JValue]
def findField(p: JField => Boolean): Option[JField]
//...

JSON の中の field を渡すには *Filed 関数を使います。そして JSONの中の値を渡すときには名前に'filed'が無い関数を使用します。

2.2 ->

Path 式はバージョン2.2以降変わりました。以前のバージョンでは式の使用で不必要な複雑な JField が返っていた。もし以下のようなパターンマッチングの path式を使用している場合:

val JField("bar", JInt(x)) = json \ "foo" \ "bar"

次のように変更が必要です:

val JInt(x) = json \ "foo" \ "bar"

JSON の解析

有効な json は内部ASTフォーマットに解析されることができる。 native を使用した場合:

scala> import org.json4s._
scala> import org.json4s.native.JsonMethods._

scala> parse(""" { "numbers" : [1, 2, 3, 4] } """)
res0: org.json4s.JsonAST.JValue =
      JObject(List((numbers,JArray(List(JInt(1), JInt(2), JInt(3), JInt(4))))))

scala> parse("""{"name":"Toy","price":35.35}""", useBigDecimalForDouble = true)
res1: org.json4s.package.JValue =
      JObject(List((name,JString(Toy)), (price,JDecimal(35.35))))

jackson を使用した場合:

scala> import org.json4s._
scala> import org.json4s.jackson.JsonMethods._

scala> parse(""" { "numbers" : [1, 2, 3, 4] } """)
res0: org.json4s.JsonAST.JValue =
      JObject(List((numbers,JArray(List(JInt(1), JInt(2), JInt(3), JInt(4))))))

scala> parse("""{"name":"Toy","price":35.35}""", useBigDecimalForDouble = true)
res1: org.json4s.package.JValue =
      JObject(List((name,JString(Toy)), (price,JDecimal(35.35))))

JSON の生成

json を DoubleMode あるいは BigDecimalMode の２つのモードで生成することが出来る。前者はすべての 10進数の値をJDouble にマップする、後者は JDecimalにマップする。

double モードDSLの使用:

import org.json4s.JsonDSL._
// or
import org.json4s.JsonDSL.WithDouble._

big decimalモードDSLの使用:

import org.json4s.JsonDSL.WithBigDecimal._

DSL ルール

プリミティブ型は JSON プリミティブにマップする。
いずれの seq は JSON配列を生成する。

scala> val json = List(1, 2, 3)

scala> compact(render(json))

res0: String = [1,2,3]

Tuple2[String, A] はフィールドを生成する。

scala> val json = ("name" -> "joe")

scala> compact(render(json))
res1: String = {"name":"joe"}

~ 演算子はフィールドに組み合わされたオブジェクトを生成する。

scala> val json = ("name" -> "joe") ~ ("age" -> 35)

scala> compact(render(json))
res2: String = {"name":"joe","age":35}

いずれの値も Option化できる。フィールドと値はそれが値を持たない時には取り除かれる。

scala> val json = ("name" -> "joe") ~ ("age" -> Some(35))

scala> compact(render(json))
res3: String = {"name":"joe","age":35}

scala> val json = ("name" -> "joe") ~ ("age" -> (None: Option[Int]))

scala> compact(render(json))
res4: String = {"name":"joe"}

dsl拡張 dslを拡張あなた自身のクラスと共にスコープ内に引数の適合する暗黙的変換が必要:

type DslConversion = T => JValue

例

object JsonExample extends App {
  import org.json4s._
  import org.json4s.JsonDSL._
  import org.json4s.jackson.JsonMethods._

  case class Winner(id: Long, numbers: List[Int])
  case class Lotto(id: Long, winningNumbers: List[Int], winners: List[Winner], drawDate: Option[java.util.Date])

  val winners = List(Winner(23, List(2, 45, 34, 23, 3, 5)), Winner(54, List(52, 3, 12, 11, 18, 22)))
  val lotto = Lotto(5, List(2, 45, 34, 23, 7, 5, 3), winners, None)

  val json =
    ("lotto" ->
      ("lotto-id" -> lotto.id) ~
      ("winning-numbers" -> lotto.winningNumbers) ~
      ("draw-date" -> lotto.drawDate.map(_.toString)) ~
      ("winners" ->
        lotto.winners.map { w =>
          (("winner-id" -> w.id) ~
           ("numbers" -> w.numbers))}))

  println(compact(render(json)))
}

scala> JsonExample
{"lotto":{"lotto-id":5,"winning-numbers":[2,45,34,23,7,5,3],"winners":
[{"winner-id":23,"numbers":[2,45,34,23,3,5]},{"winner-id":54,"numbers":[52,3,12,11,18,22]}]}}

サンプルは以下の書式を揃えられたJSONを生成します。注意 draw-date フィールドはその値がNoneの為出力されていない:

scala> pretty(render(JsonExample.json))

{
  "lotto":{
    "lotto-id":5,
    "winning-numbers":[2,45,34,23,7,5,3],
    "winners":[{
      "winner-id":23,
      "numbers":[2,45,34,23,3,5]
    },{
      "winner-id":54,
      "numbers":[52,3,12,11,18,22]
    }]
  }
}

結合と差分

Please see more examples in MergeExamples.scala and DiffExamples.scala.

二つのJSONはお互いに結合したり、差分を取ったりすることが可能。詳細はサンプル MergeExamples.scala と DiffExamples.scalaを参照ください。

scala> import org.json4s._

scala> import org.json4s.jackson.JsonMethods._

scala> val lotto1 = parse("""{
         "lotto":{
           "lotto-id":5,
           "winning-numbers":[2,45,34,23,7,5,3],
           "winners":[{
             "winner-id":23,
             "numbers":[2,45,34,23,3,5]
           }]
         }
       }""")

scala> val lotto2 = parse("""{
         "lotto":{
           "winners":[{
             "winner-id":54,
             "numbers":[52,3,12,11,18,22]
           }]
         }
       }""")

scala> val mergedLotto = lotto1 merge lotto2

scala> pretty(render(mergedLotto))
res0: String =
{
  "lotto":{
    "lotto-id":5,
    "winning-numbers":[2,45,34,23,7,5,3],
    "winners":[{
      "winner-id":23,
      "numbers":[2,45,34,23,3,5]
    },{
      "winner-id":54,
      "numbers":[52,3,12,11,18,22]
    }]
  }
}

scala> val Diff(changed, added, deleted) = mergedLotto diff lotto1
changed: org.json4s.JsonAST.JValue = JNothing
added: org.json4s.JsonAST.JValue = JNothing
deleted: org.json4s.JsonAST.JValue = JObject(List((lotto,JObject(List(JField(winners,
JArray(List(JObject(List((winner-id,JInt(54)), (numbers,JArray(
List(JInt(52), JInt(3), JInt(12), JInt(11), JInt(18), JInt(22))))))))))))))

JSON へのクエリ

"LINQ" style

JSON は for-comprehension を用いて抽出することが出来る。詳細はサンプルJsonQueryExamples.scalaを参照ください。

scala> import org.json4s._
scala> import org.json4s.native.JsonMethods._

scala> val json = parse("""
         { "name": "joe",
           "children": [
             {
               "name": "Mary",
               "age": 5
             },
             {
               "name": "Mazy",
               "age": 3
             }
           ]
         }
       """)

scala> for {
         JObject(child) <- json
         JField("age", JInt(age))  <- child
       } yield age
res0: List[BigInt] = List(5, 3)

scala> for {
         JObject(child) <- json
         JField("name", JString(name)) <- child
         JField("age", JInt(age)) <- child
         if age > 4
       } yield (name, age)
res1: List[(String, BigInt)] = List((Mary,5))

XPath + HOFs

Json AST XPATHライクな機能をつかって問い合わせされることが出来る。下記のREPLセッションは '\','\\','find','filter','transform','remove','values'関数の使用方法である。

JSON サンプル:

{
  "person": {
    "name": "Joe",
    "age": 35,
    "spouse": {
      "person": {
        "name": "Marilyn",
        "age": 33
      }
    }
  }
}

DSL構文への変換:

scala> import org.json4s._
scala> import org.json4s.native.JsonMethods._

あるいは

scala> import org.json4s.jackson.JsonMethods._
scala> import org.json4s.JsonDSL._

scala> val json =
  ("person" ->
    ("name" -> "Joe") ~
    ("age" -> 35) ~
    ("spouse" ->
      ("person" ->
        ("name" -> "Marilyn") ~
        ("age" -> 33)
      )
    )
  )

scala> json \\ "spouse"
res0: org.json4s.JsonAST.JValue = JObject(List(
      (person,JObject(List((name,JString(Marilyn)), (age,JInt(33)))))))

scala> compact(render(res0))
res1: String = {"person":{"name":"Marilyn","age":33}}

scala> compact(render(json \\ "name"))
res2: String = {"name":"Joe","name":"Marilyn"}

scala> compact(render((json removeField { _ == JField("name", JString("Marilyn")) }) \\ "name"))
res3: String = "Joe"

scala> compact(render(json \ "person" \ "name"))
res4: String = "Joe"

scala> compact(render(json \ "person" \ "spouse" \ "person" \ "name"))
res5: String = "Marilyn"

scala> json findField {
         case JField("name", _) => true
         case _ => false
       }
res6: Option[org.json4s.JsonAST.JValue] = Some((name,JString(Joe)))

scala> json filterField {
         case JField("name", _) => true
         case _ => false
       }
res7: List[org.json4s.JsonAST.JField] = List(JField(name,JString(Joe)), JField(name,JString(Marilyn)))

scala> json transformField {
         case JField("name", JString(s)) => ("NAME", JString(s.toUpperCase))
       }
res8: org.json4s.JsonAST.JValue = JObject(List((person,JObject(List(
(NAME,JString(JOE)), (age,JInt(35)), (spouse,JObject(List(
(person,JObject(List((NAME,JString(MARILYN)), (age,JInt(33)))))))))))))

scala> json.values
res8: scala.collection.immutable.Map[String,Any] = Map(person -> Map(name -> Joe, age -> 35, spouse -> Map(person -> Map(name -> Marilyn, age -> 33))))

インデックス化された path式も動作し、値は型式（データ型を表す式）を使ってアンボックスできます。

scala> val json = parse("""
         { "name": "joe",
           "children": [
             {
               "name": "Mary",
               "age": 5
             },
             {
               "name": "Mazy",
               "age": 3
             }
           ]
         }
       """)

scala> (json \ "children")(0)
res0: org.json4s.JsonAST.JValue = JObject(List((name,JString(Mary)), (age,JInt(5))))

scala> (json \ "children")(1) \ "name"
res1: org.json4s.JsonAST.JValue = JString(Mazy)

scala> json \\ classOf[JInt]
res2: List[org.json4s.JsonAST.JInt#Values] = List(5, 3)

scala> json \ "children" \\ classOf[JString]
res3: List[org.json4s.JsonAST.JString#Values] = List(Mary, Mazy)

値の抽出

case class は解析されたJSONから値を抽出し使用することが出来る。存在しない値は scala.Option型に抽出され、文字列は自動的に java.util.Dates 型に変換される。詳細はサンプルExtractionExampleSpec.scalaを参照ください。

scala> import org.json4s._
scala> import org.json4s.jackson.JsonMethods._

scala> implicit val formats = DefaultFormats // Brings in default date formats etc.

scala> case class Child(name: String, age: Int, birthdate: Option[java.util.Date])
scala> case class Address(street: String, city: String)
scala> case class Person(name: String, address: Address, children: List[Child])

scala> val json = parse("""
         { "name": "joe",
           "address": {
             "street": "Bulevard",
             "city": "Helsinki"
           },
           "children": [
             {
               "name": "Mary",
               "age": 5,
               "birthdate": "2004-09-04T18:06:22Z"
             },
             {
               "name": "Mazy",
               "age": 3
             }
           ]
         }
       """)

scala> json.extract[Person]
res0: Person = Person(joe,Address(Bulevard,Helsinki),List(Child(Mary,5,Some(Sat Sep 04 18:06:22 EEST 2004)), Child(Mazy,3,None)))

scala> val addressJson = json  \ "address"  // Extract address object
scala> addressJson.extract[Address]
res1: Address = Address(Bulevard,Helsinki)

scala> (json \ "children").extract[List[Child]]  // Extract list of objects
res2: List[Child] = List(Child(Mary,5,Some(Sat Sep 04 23:36:22 IST 2004)), Child(Mazy,3,None))

デフォルトではコンストラクタパラメータ名は json フィールド名に一致する必要があります。しかし時々 json フィールド名が Scalaの識別子として許されていない文字を含んでいます。二つの解決方法があります。（サンプルLottoExample.scala for bigger example)を参照ください）

back ticks(`)を使う.

scala> case class Person(`first-name`: String)

AST後処理に transform 関数を使う。

scala> case class Person(firstname: String)
scala> json transformField {
         case ("first-name", x) => ("firstname", x)
       }

もし json フィールド名がスネークケース(例: separated_by_underscores)を使用していてケースクラスがキャメルケース（例：firstLetterLowercaseAndNextWordsCapitalized）を使っている場合抽出時にcamelizeKeys メソッドを使って変換することができます。

scala> import org.json4s._
scala> import org.json4s.native.JsonMethods._
scala> implicit val formats = DefaultFormats
scala> val json = parse("""{"first_name":"Mary"}""")
scala> case class Person(firstName: String)

scala> json.camelizeKeys.extract[Person]
res0: Person = Person(Mazy)

キャメルケースのフィールドをスネークケースのキーのjson に変換する方法の詳細はシリアライズの項目を見てください。

抽出関数は case class が補助コンストラクターを持っている場合、もっとも一致するコンストラクターを見つけることを試みます。例えば JSON {"price":350} を次のcase class に抽出する場合主コンストラクタの代わりに補助コンストラクタを使用します。

scala> case class Bike(make: String, price: Int) {
         def this(price: Int) = this("Trek", price)
       }
scala> parse(""" {"price":350} """).extract[Bike]
res0: Bike = Bike(Trek,350)

プリミティブ値はJSONプリミティブあるいはフィールドに抽出されます。

scala> (json \ "name").extract[String]
res0: String = "joe"

scala> ((json \ "children")(0) \ "birthdate").extract[Date]
res1: java.util.Date = Sat Sep 04 21:06:22 EEST 2004

日付フォーマットは 'DefaultFormats'（あるいは暗黙的トレイト 'Format'）によって上書きされ変更されます。

scala> implicit val formats = new DefaultFormats {
         override def dateFormatter = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'")
       }

JSON オブジェクトは Map[String, _]に抽出することもできる。おのおののフィールドはMapの(キー、値)のペアとなる。

scala> val json = parse("""
         {
           "name": "joe",
           "addresses": {
             "address1": {
               "street": "Bulevard",
               "city": "Helsinki"
             },
             "address2": {
               "street": "Soho",
               "city": "London"
             }
           }
         }""")

scala> case class PersonWithAddresses(name: String, addresses: Map[String, Address])
scala> json.extract[PersonWithAddresses]
res0: PersonWithAddresses("joe", Map("address1" -> Address("Bulevard", "Helsinki"),
                                     "address2" -> Address("Soho", "London")))

シリアル化

Case class はシリアライズ、デシリアライズされることができる。
詳細はサンプル SerializationExamples.scala を参照ください。

scala> import org.json4s._
scala> import org.json4s.native.Serialization
scala> import org.json4s.native.Serialization.{read, write}

scala> implicit val formats = Serialization.formats(NoTypeHints)

scala> val ser = write(Child("Mary", 5, None))

scala> read[Child](ser)
res1: Child = Child(Mary,5,None)

もし native の代わりに jackson を使っている場合:

scala> import org.json4s._
scala> import org.json4s.jackson.Serialization
scala> import org.json4s.jackson.Serialization.{read, write}

scala> implicit val formats = Serialization.formats(NoTypeHints)

scala> val ser = write(Child("Mary", 5, None))

scala> read[Child](ser)
res1: Child = Child(Mary,5,None)

もしクラスがキャメルケースフィールド（例：firstLetterLowercaseAndNextWordsCapitalized）を使っていて、スネークケース(例: separated_by_underscores)の json を生成したくないときは snakizeKeys メソッドを使えます。

scala> val ser = write(Person("Mary"))
ser: String = {"firstName":"Mary"}
シリアル化 サポート:

scala> compact(render(parse(ser).snakizeKeys))
res0: String = {"first_name":"Mary"}

任意の深い case class グラフ
BigInt,Symbol を含むすべてのプリミティブ型
List, Seq, Array, Set と Map (注意, マップのキーは String であることが必要: Map[String, _])
scala.Option
java.util.Date
多相型List (下を参照)
再帰データ型
クラスフィールドのシリアル化(下を参照)
サポートされていない型に対するカスタムシリアライザー関数(下を参照)

多相型Listのシリアル化

多相型（や異なる型を持つ）Listのシリアル化をする際には Type hint が必要です。シリアル化されたJSONオブジェクトは 'jsonClass' という名前の追加のフィールドを得ます。

scala> trait Animal
scala> case class Dog(name: String) extends Animal
scala> case class Fish(weight: Double) extends Animal
scala> case class Animals(animals: List[Animal])

scala> implicit val formats = Serialization.formats(ShortTypeHints(List(classOf[Dog], classOf[Fish])))

scala> val ser = write(Animals(Dog("pluto") :: Fish(1.2) :: Nil))
ser: String = {"animals":[{"jsonClass":"Dog","name":"pluto"},{"jsonClass":"Fish","weight":1.2}]}

scala> read[Animals](ser)
res0: Animals = Animals(List(Dog(pluto), Fish(1.2)))

ShortTypeHints は構成されたオブジェクトのすべてのインスタンスのための短いクラス名を出力する。 FullTypeHints はフルクラス名を出力します。そのほかの方法は TypeHints トレイトを拡張することで実装可能です。

クラスフィールドのシリアル化

フィールドのシリアル化を有効にするには、FieldSerializerでいくつかの型を追加できる:

implicit val formats = DefaultFormats + FieldSerializer[WildDog]()

WildDog型（とすべてのサブ型）はすべてのフィールド（+ コンストラクタパラメータ）と共にシリアル化される。 FieldSerializerは、フィールドのシリアル化を傍受するために使用できる2つの省略可能なパラメータを受け取ります:

case class FieldSerializer[A: Manifest](
  serializer:   PartialFunction[(String, Any), Option[(String, Any)]] = Map(),
  deserializer: PartialFunction[JField, JField] = Map()
)

それらの部分関数はフィールドがシリアル化されるかデシリアル化されるその前に呼ばれます。有用な名前を変える(rename)、フィールドを無視する(ignore) 部分関数が提供されています:

val dogSerializer = FieldSerializer[WildDog](
  renameTo("name", "animalname") orElse ignore("owner"),
  renameFrom("animalname", "name"))

implicit val formats = DefaultFormats + dogSerializer

trait,class で定義されたシリアライズクラス

われわれは trait に定義された case class のサポートを追加しました。しかしそれらにはカスタムフォーマットが必要である。「なぜ」と「どうやって」を説明します。

Why?

trait の中で定義されたクラスについてはそのコンパニオンオブジェクトを取得するのは少し難しいので、デフォルト値を与える必要がある。
われわれはそれらをあてはめることはできたがそれはコンパイラがそんな case class のコンストラクタに余分なフィールドを生成するという、次の問題を引き起こす。
それらの case class のコンストラクタのはじめのフィールドは $outer と呼ばれ 定義している trait の型である。　ともかくわれわれはそのオブジェクトのインスタンスを取得する必要がある、単純な方法ではわれわれはすべての class をスキャンし、 trait で定義されているクラスを集めるられるが、しかし一つ以上ある場合どれをとればいいか？

How?

私はそれらの case class 為のコンパニオンマッピングのリストを含むようにフォーマットを拡張するということを選択しました。
つまりあなたのモジュールに属しているフォーマットを持つことで、そこでマッピングを保持することができます。そうすることでデフォルト値が動作し $outer フィールドに必要な多くのものを提供するようになります。

trait SharedModule {
  case class SharedObj(name: String, visible: Boolean = false)
}

object PingPongGame extends SharedModule
implicit val formats: Formats =
  DefaultFormats.withCompanions(classOf[PingPongGame.SharedObj] -> PingPongGame)

val inst = PingPongGame.SharedObj("jeff", visible = true)
val extr = Extraction.decompose(inst)
extr must_== JObject("name" -> JString("jeff"), "visible" -> JBool(true))
extr.extract[PingPongGame.SharedObj] must_== inst

サポートされていない型のシリアル化

あらゆる型へのカスタムシリアライザとデシリアライザ関数を差し込むことが可能。非 case class である Interval クラスがある場合（かくて、デフォルトではサポートされていない）われわれは次の提供されたシリアライザによってシリアル化可能。

scala> class Interval(start: Long, end: Long) {
         val startTime = start
         val endTime = end
       }

scala> class IntervalSerializer extends CustomSerializer[Interval](format => (
         {
           case JObject(JField("start", JInt(s)) :: JField("end", JInt(e)) :: Nil) =>
             new Interval(s.longValue, e.longValue)
         },
         {
           case x: Interval =>
             JObject(JField("start", JInt(BigInt(x.startTime))) ::
                     JField("end",   JInt(BigInt(x.endTime))) :: Nil)
         }
       ))

scala> implicit val formats = Serialization.formats(NoTypeHints) + new IntervalSerializer

カスタムシリアライザは二つの部分関数によって提供される。はじめにそれがJSONからのデータをアンパックできるか値を評価する。次に型が適合した場合望ましいJSONを生成します。

拡張

json4s-ext モジュールは抽出とシリアル化の拡張を含んでいます。以下のタイプがサポートされています。

// Lift's box
implicit val formats = org.json4s.DefaultFormats + new org.json4s.native.ext.JsonBoxSerializer

// Scala enums
implicit val formats = org.json4s.DefaultFormats + new org.json4s.ext.EnumSerializer(MyEnum)
// or
implicit val formats = org.json4s.DefaultFormats + new org.json4s.ext.EnumNameSerializer(MyEnum)

// Joda Time
implicit val formats = org.json4s.DefaultFormats ++ org.json4s.ext.JodaTimeSerializers.all

XML サポート

JSON 構造と XMLノードと相互の変換が可能です。
詳細はサンプル XmlExamples.scala を参照ください。

scala> import org.json4s.Xml.{toJson, toXml}
scala> val xml =
         <users>
           <user>
             <id>1</id>
             <name>Harry</name>
           </user>
           <user>
             <id>2</id>
             <name>David</name>
           </user>
         </users>

scala> val json = toJson(xml)
scala> pretty(render(json))
res3: String =
{
  "users":{
    "user":[{
      "id":"1",
      "name":"Harry"
    },{
      "id":"2",
      "name":"David"
    }]
  }
}

現在、上のサンプルには2つの問題があります。1つ目 id は Int に変換して欲しかったが String に変換された。これはJString(s) から JInt(s.toInt) へのマッピングをつかい容易に修正が可能です。二つ目はもっと巧妙です。変換機能はJSON配列を使うことを決めます、なぜなら XMLの中に一つ以上の userエレメントがあるからです。それゆえただ一つのuserエレメントを持つことが起こる構造的に等しいXMLドキュメントはJSON配列なしの JSONドキュメントを生成します。これはめったに望ましい結果とはならない。これら両方の問題は以下の変換関数によって修正可能である。

scala> json transformField {
         case ("id", JString(s)) => ("id", JInt(s.toInt))
         case ("user", x: JObject) => ("user", JArray(x :: Nil))
       }

他方へもサポートされる。 JSONからXMLへの変換:

scala> toXml(json)
res5: scala.xml.NodeSeq = NodeSeq(<users><user><id>1</id><name>Harry</name></user><user><id>2</id><name>David</name></user></users>)

低レベル pull parser API

極限のパフォーマンスが必要される場合のために Pull パーサ APIは提供される。それは二つの方法で解析のパフォーマンスを改善します。一つ目は中間ASTを生成しない。二つ目は残りのストリームの解析をいつでも停止、スキップできる。注意この解析スタイルは最適化の場合にのみ推奨される。上で述べられた関数 API の使用は容易である。

次のサンプルみてどのように JSONからフィールド値を解析するか検討してください。

scala> val json = """
  {
    ...
    "firstName": "John",
    "lastName": "Smith",
    "address": {
      "streetAddress": "21 2nd Street",
      "city": "New York",
      "state": "NY",
      "postalCode": 10021
    },
    "phoneNumbers": [
      { "type": "home", "number": "212 555-1234" },
      { "type": "fax", "number": "646 555-4567" }
    ],
    ...
  }"""

scala> val parser = (p: Parser) => {
         def parse: BigInt = p.nextToken match {
           case FieldStart("postalCode") => p.nextToken match {
             case IntVal(code) => code
             case _ => p.fail("expected int")
           }
           case End => p.fail("no field named 'postalCode'")
           case _ => parse
         }

         parse
       }

scala> val postalCode = parse(json, parser)
postalCode: BigInt = 10021

Pull パーサは Parser => A 関数ですこのサンプルの中では具体的には Parser => BigInt です。構造化解析は FieldStart("postalCode") トークンを見つけるまで再帰的にトークンを読み込む。その後次のトークンは IntValでなければならない、さもなくば分析は失敗する。それは解析された Integer を返し、そしてすぐに解析を中止します。

FAQ

Q1: 私はJSON オブジェクトがあり、それを case class に抽出したい。

scala> case class Person(name: String, age: Int)
scala> val json = """{"name":"joe","age":15}"""

しかし、抽出に失敗します。:

scala> parse(json).extract[Person]
org.json4s.MappingException: Parsed JSON values do not match with class constructor

A1:

抽出は REPL の中で定義された classに対しては動作しません。 scalac で定義された case class をコンパイルし、それを REPL からインポートしてください。

謝辞

The original idea for DSL syntax was taken from Lift mailing list (by Marius).
The idea for AST and rendering was taken from Real World Haskell book.

takungsk/readme_ja.md