scala-circe-json

Scala Circe JSON Processing

Overview

Circe is the standard type-safe JSON library in Scala. It provides:

• Immutable Json type
• Type-safe codecs (Encoder/Decoder)
• Cursor-based navigation (like XPath for JSON)
• Pretty printing
• Seamless case class integration

Installation

Add to build.sbt:

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

Basic Usage

Parsing JSON

import io.circe.parser._
import io.circe._

// Parse from string
val jsonString = """{"name": "Alice", "age": 30}"""
val result: Either[io.circe.ParsingFailure, Json] = parse(jsonString)

// Safe extraction
result match {
  case Right(json) => println(s"Parsed: $json")
  case Left(error) => println(s"Parse error: $error")
}

// Or with Try
val json: scala.util.Try[Json] = parse(jsonString).toTry

Creating JSON

import io.circe.syntax._

// From primitives
val str = Json.fromString("hello")
val num = Json.fromInt(42)
val bool = Json.fromBoolean(true)
val null_val = Json.Null

// Object (using syntax extension)
val obj = Json.obj(
  "name" -> Json.fromString("Alice"),
  "age" -> Json.fromInt(30)
)

// Array
val arr = Json.arr(
  Json.fromInt(1),
  Json.fromInt(2),
  Json.fromInt(3)
)

// Using tuple extension (cleaner)
val obj = Json.obj(
  "name" -> "Alice".asJson,
  "age" -> 30.asJson,
  "scores" -> List(90, 85, 88).asJson
)

Working with Json Type

val json = Json.obj(
  "name" -> "Alice".asJson,
  "age" -> 30.asJson
)

// Type checks
json.isObject    // true
json.isArray     // false
json.isNull      // false

// Conversions
json.asObject    // Option[JsonObject]
json.asArray     // Option[Vector[Json]]
json.asString    // Option[String]
json.asNumber    // Option[JsonNumber]
json.asBoolean   // Option[Boolean]

// Unsafe conversion (throws)
json.asObject.get

Navigation with Cursors

Cursors provide safe, composable navigation (like XPath):