Skip to content
<open-source>
Oeiuwq Faith Blog OpenSource Porfolio

zio/zio-json

Fast, secure JSON library with tight ZIO integration.
Source code at GitHub https://zio.dev/zio-json
zio/zio-json.json
{
  "createdAt": "2020-07-03T16:46:04Z",
  "defaultBranch": "series/2.x",
  "description": "Fast, secure JSON library with tight ZIO integration.",
  "fullName": "zio/zio-json",
  "homepage": "https://zio.dev/zio-json",
  "language": "Scala",
  "name": "zio-json",
  "pushedAt": "2025-11-26T01:59:21Z",
  "stargazersCount": 427,
  "topics": [
    "json",
    "performance",
    "scala",
    "security",
    "zio"
  ],
  "updatedAt": "2025-11-25T02:54:11Z",
  "url": "https://github.com/zio/zio-json"
}

[//] !: # (This file was autogenerated using zio-sbt-website plugin via sbt generateReadme command.) [//] !: # (So please do not edit it manually. Instead, change “docs/index.md” file or sbt setting keys) [//] !: # (e.g. “readmeDocumentation” and “readmeSupport”.)

ZIO JSON

Section titled “ZIO JSON”

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

Production Ready Sonatype Releases Sonatype Snapshots javadoc ZIO JSON

Introduction

Section titled “Introduction”

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 runs on JDK 11+ JVMs.
  • Simple small codebase, concise documentation that covers everything.
  • Helpful errors are readable by humans and machines.
  • ZIO Integration so nothing more is required.

Installation

Section titled “Installation”

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

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

Example

Section titled “Example”

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

import zio.json._

Say we want to be able to read some JSON like

{"curvature":0.5}

into a Scala case class

final case class Banana(curvature: Double)

To do this, we derive an instance of the JsonDecoder typeclass for Banana.

final case class Banana(curvature: Double) derives JsonDecoder

[!NOTE]

In scala 2, we need to use the zio-json semi-automatic derivation. It is best practice to put it on the companion of Banana, like so

object Banana {
  implicit val decoder: JsonDecoder[Banana] = DeriveJsonDecoder.gen[Banana]
}

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 derive a JsonEncoder

final case class Banana(curvature: Double) derives JsonEncoder


scala> Banana(0.5).toJson
val res: String = {"curvature":0.5}


scala> Banana(0.5).toJsonPretty
val res: String =
{
  "curvature" : 0.5
}

[!NOTE]

In scala 2:

object Banana {
  ...
  implicit val encoder: JsonEncoder[Banana] = DeriveJsonEncoder.gen[Banana]
}

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

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

Say we extend our data model to include more data types

enum Fruit {
  case Banana(curvature: Double)
  case Apple(poison: Boolean)
}

we can generate the encoder and decoder for the entire sealed family using JsonCodec

enum Fruit derives JsonCodec {
  case Banana(curvature: Double)
  case Apple(poison: Boolean)
}

[!NOTE]

In scala 2:

import zio.json._


sealed trait Fruit
final case class Banana(curvature: Double) extends Fruit
final case class Apple(poison: Boolean)    extends Fruit


object Fruit {
  implicit val decoder: JsonDecoder[Fruit] =
    DeriveJsonDecoder.gen[Fruit]


  implicit val encoder: JsonEncoder[Fruit] =
    DeriveJsonEncoder.gen[Fruit]
}


val json1         = """{ "Banana":{ "curvature":0.5 }}"""
val json2         = """{ "Apple": { "poison": false }}"""
val malformedJson = """{ "Banana":{ "curvature": true }}"""


json1.fromJson[Fruit]
json2.fromJson[Fruit]
malformedJson.fromJson[Fruit]


List(Apple(false), Banana(0.4)).toJsonPretty

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.

How

Section titled “How”

High performance is achieved by decoding JSON directly from the input source into business objects. See benchmark results of throughput and allocation rate for synthetic and real-world message samples in comparison with other JSON parsers here.

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

Fast compilation and future-proofing is possible thanks to Magnolia which allows us to generate boilerplate in a way that will survive the exodus to Scala 3. zio-json is internally implemented using a java.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 in Functional Programming for Mortals.

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

Documentation

Section titled “Documentation”

Learn more on the ZIO JSON homepage!

Contributing

Section titled “Contributing”

For the general guidelines, see ZIO contributor’s guide.

Code of Conduct

Section titled “Code of Conduct”

See the Code of Conduct

Support

Section titled “Support”

Come chat with us on [![Badge-Discord]][Link-Discord].

[Badge-Discord] !: https://img.shields.io/discord/629491597070827530?logo=discord “chat on discord” [Link-Discord] !: https://discord.gg/2ccFBr4 “Discord”

Acknowledgement

Section titled “Acknowledgement”

License

Section titled “License”

[License]!(LICENSE)