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.