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 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.12.3" 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 )
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.
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
Other subprojects bring in dependencies on Jawn (for parsing in the
subproject), Shapeless (for automatic codec derivation in
but it would be possible to replace the functionality provided by these subprojects with alternative
implementations that use other libraries.
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
See the Parsing page for more details.
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.
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
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
auto, incomplete decoders will not work (see
See the Encoding and Decoding page for more details.
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.
I’d like to provide more complete test coverage (in part via Discipline), but it’s early days for this.
circe is developed with a focus on performance. See the Performance page for details.
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.