Repository files navigation

ZIO Json is a fast and secure JSON library with tight ZIO integration.

The goal of this project is to create the best all-round JSON library for Scala:

• Performance to handle more requests per second than the incumbents, i.e. reduced operational costs.
• Security to mitigate against adversarial JSON payloads that threaten the capacity of the server.
• Fast Compilation no shapeless, no type astronautics.
• Future-Proof, prepared for Scala 3 and next-generation Java.
• Simple small codebase, concise documentation that covers everything.
• Helpful errors are readable by humans and machines.
• ZIO Integration so nothing more is required.

In order to use this library, we need to add the following line in ourbuild.sbt file:

libraryDependencies+="dev.zio"%%"zio-json"%"0.6.2"

Let's try a simple example of encoding and decoding JSON using ZIO JSON.

All the following code snippets assume that the following imports have been declared

importzio.json._

Say we want to be able to read some JSON like

{"curvature":0.5}

into a Scalacase class

caseclassBanana(curvature:Double)

To do this, we create aninstance of theJsonDecoder typeclass forBanana using thezio-json code generator. It is best practice to put it on the companion ofBanana, like so

objectBanana {implicitvaldecoder:JsonDecoder[Banana]=DeriveJsonDecoder.gen[Banana]}

Note: If you’re using Scala 3 and your case class is defining default parameters,-Yretain-trees needs to be added toscalacOptions.

Now we can parse JSON into our object

scala> """{"curvature":0.5}""".fromJson[Banana]val res: Either[String, Banana] = Right(Banana(0.5))

Likewise, to produce JSON from our data we define aJsonEncoder

objectBanana {  ...implicitvalencoder:JsonEncoder[Banana]=DeriveJsonEncoder.gen[Banana]}scala>Banana(0.5).toJsonvalres:String= {"curvature":0.5}scala>Banana(0.5).toJsonPrettyvalres:String={"curvature":0.5}

And bad JSON will produce an error injq syntax with an additional piece of contextual information (in parentheses)

scala> """{"curvature": womp}""".fromJson[Banana]val res: Either[String, Banana] = Left(.curvature(expected a Double))

Say we extend our data model to include more data types

sealedtraitFruitcaseclassBanana(curvature:Double)extendsFruitcaseclassApple (poison:Boolean)extendsFruit

we can generate the encoder and decoder for the entiresealed family

objectFruit {implicitvaldecoder:JsonDecoder[Fruit]=DeriveJsonDecoder.gen[Fruit]implicitvalencoder:JsonEncoder[Fruit]=DeriveJsonEncoder.gen[Fruit]}

allowing us to load the fruit based on a single field type tag in the JSON

scala> """{"Banana":{"curvature":0.5}}""".fromJson[Fruit]val res: Either[String, Fruit] = Right(Banana(0.5))scala> """{"Apple":{"poison":false}}""".fromJson[Fruit]val res: Either[String, Fruit] = Right(Apple(false))

Almost all of the standard library data types are supported as fields on the case class, and it is easy to add support if one is missing.

importzio.json._sealedtraitFruitextendsProductwithSerializablecaseclassBanana(curvature:Double)extendsFruitcaseclassApple(poison:Boolean)extendsFruitobjectFruit {implicitvaldecoder:JsonDecoder[Fruit]=DeriveJsonDecoder.gen[Fruit]implicitvalencoder:JsonEncoder[Fruit]=DeriveJsonEncoder.gen[Fruit]}valjson1="""{ "Banana":{ "curvature":0.5 }}"""valjson2="""{ "Apple": { "poison": false }}"""valmalformedJson="""{ "Banana":{ "curvature": true }}"""json1.fromJson[Fruit]json2.fromJson[Fruit]malformedJson.fromJson[Fruit]List(Apple(false),Banana(0.4)).toJsonPretty

Extremeperformance is achieved by decoding JSON directly from the input source into business objects (inspired byplokhotnyuk). Although not a requirement, the latest advances inJava Loom can be used to support arbitrarily large payloads with near-zero overhead.

Best in classsecurity is achieved with an aggressiveearly exit strategy that avoids costly stack traces, even when parsing malformed numbers. Malicious (and badly formed) payloads are rejected before finishing reading.

Fast compilation andfuture-proofing is possible thanks toMagnolia which allows us to generate boilerplate in a way that will survive the exodus to Scala 3.zio-json is internally implemented using ajava.io.Reader /java.io.Writer-like interface, which is making a comeback to center stage in Loom.

Simplicity is achieved by using well-known software patterns and avoiding bloat. The only requirement to use this library is to know about Scala's encoding of typeclasses, described inFunctional Programming for Mortals.

Helpful errors are produced in the form of ajq query, with a note about what went wrong, pointing to the exact part of the payload that failed to parse.

Learn more on theZIO JSON homepage!

For the general guidelines, see ZIOcontributor's guide.

See theCode of Conduct

Come chat with us on.

• UsesJsonTestSuite to test parsing. (c) 2016 Nicolas Seriot)

• UsesYourKit Java Profiler for performance optimisation.

License