{"id":13801565,"url":"https://github.com/zio/zio-json","last_synced_at":"2025-05-14T21:07:08.139Z","repository":{"id":38848176,"uuid":"276946584","full_name":"zio/zio-json","owner":"zio","description":"Fast, secure JSON library with tight ZIO integration.","archived":false,"fork":false,"pushed_at":"2025-05-10T09:25:21.000Z","size":8701,"stargazers_count":420,"open_issues_count":76,"forks_count":148,"subscribers_count":19,"default_branch":"series/2.x","last_synced_at":"2025-05-10T10:29:26.061Z","etag":null,"topics":["json","performance","scala","security","zio"],"latest_commit_sha":null,"homepage":"https://zio.dev/zio-json","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-07-03T16:46:04.000Z","updated_at":"2025-05-10T09:25:25.000Z","dependencies_parsed_at":"2024-01-22T12:17:20.891Z","dependency_job_id":"d0a77c9a-69a3-4eb7-aa71-a273b488b09d","html_url":"https://github.com/zio/zio-json","commit_stats":null,"previous_names":[],"tags_count":77,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zio%2Fzio-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zio","download_url":"https://codeload.github.com/zio/zio-json/tar.gz/refs/heads/series/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227612,"owners_count":22035669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","performance","scala","security","zio"],"created_at":"2024-08-04T00:01:24.445Z","updated_at":"2025-05-14T21:07:03.110Z","avatar_url":"https://github.com/zio.png","language":"Scala","readme":"[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.)\n[//]: # (So please do not edit it manually. Instead, change \"docs/index.md\" file or sbt setting keys)\n[//]: # (e.g. \"readmeDocumentation\" and \"readmeSupport\".)\n\n# ZIO JSON\n\n[ZIO Json](https://github.com/zio/zio-json) is a fast and secure JSON library with tight ZIO integration.\n\n[![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-json_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-json_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-json_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-json_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-json-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-json-docs_2.13) [![ZIO JSON](https://img.shields.io/github/stars/zio/zio-json?style=social)](https://github.com/zio/zio-json)\n\n## Introduction\n\nThe goal of this project is to create the best all-round JSON library for Scala:\n\n- **Performance** to handle more requests per second than the incumbents, i.e. reduced operational costs.\n- **Security** to mitigate against adversarial JSON payloads that threaten the capacity of the server.\n- **Fast Compilation** no shapeless, no type astronautics.\n- **Future-Proof**, prepared for Scala 3 and next-generation Java.\n- **Simple** small codebase, concise documentation that covers everything.\n- **Helpful errors** are readable by humans and machines.\n- **ZIO Integration** so nothing more is required.\n\n## Installation\n\nIn order to use this library, we need to add the following line in our `build.sbt` file:\n\n```scala\nlibraryDependencies += \"dev.zio\" %% \"zio-json\" % \"0.6.2\"\n```\n\n## Example\n\nLet's try a simple example of encoding and decoding JSON using ZIO JSON.\n\nAll the following code snippets assume that the following imports have been declared\n\n```scala\nimport zio.json._\n```\n\nSay we want to be able to read some JSON like\n\n```json\n{\"curvature\":0.5}\n```\n\ninto a Scala `case class`\n\n```scala\ncase class Banana(curvature: Double)\n```\n\nTo do this, we create an *instance* of the `JsonDecoder` typeclass for `Banana` using the `zio-json` code generator. It is best practice to put it on the companion of `Banana`, like so\n\n```scala\nobject Banana {\n  implicit val decoder: JsonDecoder[Banana] = DeriveJsonDecoder.gen[Banana]\n}\n```\n\n_Note: If you’re using Scala 3 and your case class is defining default parameters, `-Yretain-trees` needs to be added to `scalacOptions`._\n\nNow we can parse JSON into our object\n\n```\nscala\u003e \"\"\"{\"curvature\":0.5}\"\"\".fromJson[Banana]\nval res: Either[String, Banana] = Right(Banana(0.5))\n```\n\nLikewise, to produce JSON from our data we define a `JsonEncoder`\n\n```scala\nobject Banana {\n  ...\n  implicit val encoder: JsonEncoder[Banana] = DeriveJsonEncoder.gen[Banana]\n}\n\nscala\u003e Banana(0.5).toJson\nval res: String = {\"curvature\":0.5}\n\nscala\u003e Banana(0.5).toJsonPretty\nval res: String =\n{\n  \"curvature\" : 0.5\n}\n```\n\nAnd bad JSON will produce an error in `jq` syntax with an additional piece of contextual information (in parentheses)\n\n```\nscala\u003e \"\"\"{\"curvature\": womp}\"\"\".fromJson[Banana]\nval res: Either[String, Banana] = Left(.curvature(expected a Double))\n```\n\nSay we extend our data model to include more data types\n\n```scala\nsealed trait Fruit\ncase class Banana(curvature: Double) extends Fruit\ncase class Apple (poison: Boolean)   extends Fruit\n```\n\nwe can generate the encoder and decoder for the entire `sealed` family\n\n```scala\nobject Fruit {\n  implicit val decoder: JsonDecoder[Fruit] = DeriveJsonDecoder.gen[Fruit]\n  implicit val encoder: JsonEncoder[Fruit] = DeriveJsonEncoder.gen[Fruit]\n}\n```\n\nallowing us to load the fruit based on a single field type tag in the JSON\n\n```\nscala\u003e \"\"\"{\"Banana\":{\"curvature\":0.5}}\"\"\".fromJson[Fruit]\nval res: Either[String, Fruit] = Right(Banana(0.5))\n\nscala\u003e \"\"\"{\"Apple\":{\"poison\":false}}\"\"\".fromJson[Fruit]\nval res: Either[String, Fruit] = Right(Apple(false))\n```\n\nAlmost 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.\n\n```scala\nimport zio.json._\n\nsealed trait Fruit                   extends Product with Serializable\ncase class Banana(curvature: Double) extends Fruit\ncase class Apple(poison: Boolean)    extends Fruit\n\nobject Fruit {\n  implicit val decoder: JsonDecoder[Fruit] =\n    DeriveJsonDecoder.gen[Fruit]\n\n  implicit val encoder: JsonEncoder[Fruit] =\n    DeriveJsonEncoder.gen[Fruit]\n}\n\nval json1         = \"\"\"{ \"Banana\":{ \"curvature\":0.5 }}\"\"\"\nval json2         = \"\"\"{ \"Apple\": { \"poison\": false }}\"\"\"\nval malformedJson = \"\"\"{ \"Banana\":{ \"curvature\": true }}\"\"\"\n\njson1.fromJson[Fruit]\njson2.fromJson[Fruit]\nmalformedJson.fromJson[Fruit]\n\nList(Apple(false), Banana(0.4)).toJsonPretty\n```\n\n# How\n\nExtreme **performance** is achieved by decoding JSON directly from the input source into business objects (inspired by [plokhotnyuk](https://github.com/plokhotnyuk/jsoniter-scala)). Although not a requirement, the latest advances in [Java Loom](https://wiki.openjdk.java.net/display/loom/Main) can be used to support arbitrarily large payloads with near-zero overhead.\n\nBest 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.\n\n**Fast compilation** and **future-proofing** is possible thanks to [Magnolia](https://propensive.com/opensource/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`](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/io/Reader.html) / [`java.io.Writer`](https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/io/Writer.html)-like interface, which is making a comeback to center stage in Loom.\n\n**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](https://leanpub.com/fpmortals/read#leanpub-auto-functionality).\n\n**Helpful errors** are produced in the form of a [`jq`](https://stedolan.github.io/jq/) query, with a note about what went wrong, pointing to the exact part of the payload that failed to parse.\n\n## Documentation\n\nLearn more on the [ZIO JSON homepage](https://zio.dev/zio-json/)!\n\n## Contributing\n\nFor the general guidelines, see ZIO [contributor's guide](https://zio.dev/contributor-guidelines).\n\n## Code of Conduct\n\nSee the [Code of Conduct](https://zio.dev/code-of-conduct)\n\n## Support\n\nCome chat with us on [![Badge-Discord]][Link-Discord].\n\n[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord \"chat on discord\"\n[Link-Discord]: https://discord.gg/2ccFBr4 \"Discord\"\n\n## Acknowledgement\n\n- Uses [JsonTestSuite](https://github.com/nst/JSONTestSuite) to test parsing. (c) 2016 Nicolas Seriot)\n\n- Uses [YourKit Java Profiler](https://www.yourkit.com/java/profiler/) for performance optimisation. ![YourKit Logo](https://www.yourkit.com/images/yklogo.png)\n\n## License\n\n[License](LICENSE)\n","funding_links":[],"categories":["Table of Contents"],"sub_categories":["JSON"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzio%2Fzio-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzio%2Fzio-json/lists"}