Build status Coverage status Gitter Maven Central

circe (pronounced SUR-see, or KEER-kee in classical Greek, or CHEER-chay in Ecclesiastical Latin) is a JSON library for Scala (and Scala.js).

circe’s working title was jfc, which stood for “JSON for cats”. The name was changed for a number of reasons.

Quick start

circe is published to Maven Central and cross-built for Scala 2.12 and 2.13, so you can just add the following to your build:

val circeVersion = "0.14.1"

libraryDependencies ++= Seq(
  "io.circe" %% "circe-core",
  "io.circe" %% "circe-generic",
  "io.circe" %% "circe-parser"
).map(_ % circeVersion)

In case of large or deep-nested case classes, there is a chance to get stack overflow during compilation, please refer to known-issues for workaround.

If you’re using circe-generic-extra’s @JsonCodec macro annotations, you’ll need to add -Ymacro-annotations to your compiler options on Scala 2.13, or to include the Macro Paradise compiler plugin in your build on earlier Scala versions:

addCompilerPlugin(
  "org.scalamacros" % "paradise" % "2.1.1" cross CrossVersion.full
)

Then type sbt console to start a REPL and then paste the following (this will also work from the root directory of this repository):

import io.circe._, io.circe.generic.auto._, io.circe.parser._, io.circe.syntax._

sealed trait Foo
case class Bar(xs: Vector[String]) extends Foo
case class Qux(i: Int, d: Option[Double]) extends Foo

val foo: Foo = Qux(13, Some(14.0))

val json = foo.asJson.noSpaces
println(json)

val decodedFoo = decode[Foo](json)
println(decodedFoo)

Alternatively you can experiment with Circe directly in your browser by clicking the Run button in the code block and making modifications in the code.

No boilerplate, no runtime reflection.

Why?

Argonaut is a great library. It’s by far the best JSON library for Scala, and the best JSON library on the JVM. If you’re doing anything with JSON in Scala, you should be using Argonaut.

circe is a fork of Argonaut with a few important differences.

Dependencies and modularity

circe depends on cats instead of Scalaz, and the core project has only one dependency (cats-core).

Other subprojects bring in dependencies on Jawn (for parsing in the jawn subproject), Shapeless (for automatic codec derivation in generic), but it would be possible to replace the functionality provided by these subprojects with alternative implementations that use other libraries.

Parsing

circe doesn’t include a JSON parser in the core project, which is focused on the JSON AST, zippers, and codecs. The jawn subproject provides support for parsing JSON via a Jawn facade. Jawn is fast, it offers asynchronous parsing, and best of all it lets us drop a lot of the fussiest code in Argonaut. The circe-jackson project supports using Jackson for both parsing and printing.

circe also provides a parser subproject that provides parsing support for Scala.js, with JVM parsing provided by io.circe.jawn and JavaScript parsing from scalajs.js.JSON.

See the Parsing page for more details.

Lenses

circe doesn’t use or provide lenses in the core project. This is related to the first point above, since Monocle has a Scalaz dependency, but we also feel that it simplifies the API. The 0.3.0 release added an experimental optics subproject that provides Monocle lenses.

See the Optics page for more details.

Codec derivation

circe does not use macros or provide any kind of automatic derivation in the core project. Instead of Argonaut’s limited macro-based derivation (which does not support sealed trait hierarchies, for example), circe includes a subproject (generic) that provides generic codec derivation using Shapeless.

This subproject is currently a simplified port of argonaut-shapeless that provides fully automatic derivation of instances for case classes and sealed trait hierarchies. It also includes derivation of “incomplete” case class instances (see my recent blog post for details). Note that if you use -Ypartial-unification and auto, incomplete decoders will not work (see #724).

See the Encoding and Decoding page for more details.

Aliases

circe aims to simplify Argonaut’s API by removing all operator aliases. This is largely a matter of personal taste, and may change in the future.

Testing

I’d like to provide more complete test coverage (in part via Discipline), but it’s early days for this.

Performance

circe is developed with a focus on performance. See the Performance page for details.

License

circe is licensed under the Apache License, Version 2.0 (the “License”); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.