<commit_before>---
menu: main
weight: 310
title: JSON handling
---

## Add the JSON support module(s)

http4s-core does not include JSON support, but integration with three
popular Scala JSON libraries are supported as modules.

### Circe

The http4s team recommends circe.  Only http4s-circe is required for
basic interop with circe, but to follow this tutorial, install all three:

```scala
val http4sVersion = "{{< version "http4s.doc" >}}"

libraryDependencies ++= Seq(
  "org.http4s" %% "http4s-circe" % http4sVersion,
  // Optional for auto-derivation of JSON codecs
  "io.circe" %% "circe-generic" % "{{< version circe >}}",
  // Optional for string interpolation to JSON model
  "io.circe" %% "circe-literal" % "{{< version circe >}}"
)

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

### Argonaut

Circe is a fork of argonaut, another popular JSON library in the Scala
community.  The functionality is similar:

```scala
libraryDependencies += Seq(
  "org.http4s" %% "http4s-argonaut" % http4sVersion,
  // Optional for auto-derivation of JSON codecs
  "com.github.alexarchambault" %% "argonaut-shapeless_6.2" % "{{< version "argonaut-shapeless_6.2" >}}"
)
```

For those not ready to upgrade to argonaut-6.2, an `http4s-argonaut61`
is also available.  It is source compatible, but compiled against
Argonaut 6.1.

### Json4s

Json4s is less functionally pure than Circe or Argonaut, but older and
integrated with many Scala libraries.  It comes with two backends.
You should pick one of these dependencies:

```scala
libraryDependencies += "org.http4s" %% "http4s-json4s-native" % http4sVersion
libraryDependencies += "org.http4s" %% "http4s-json4s-jackson" % http4sVersion
```

There is no extra codec derivation library for json4s, as it generally
bases its codecs on runtime reflection.

## Sending raw JSON

Let's create a function to produce a simple JSON greeting with circe:

```tut:book
import cats.effect._
import io.circe._
import io.circe.literal._
import org.http4s._
import org.http4s.dsl.io._

def hello(name: String): Json =
  json"""{"hello": $name}"""

val greeting = hello("world")
```

We now have a JSON value, but we don't have enough to render it:

```tut:fail
Ok(greeting).unsafeRunSync
```

To encode a Scala value of type `A` into an entity, we need an
`EntityEncoder[A]` in scope.  The http4s-circe module includes a
`org.http4s.circe` object, which gives us exactly this for an
`io.circe.Json` value:

```tut:book
import org.http4s.circe._
<commit_msg>Silence some imports in the json documentation<commit_after>---
menu: main
weight: 310
title: JSON handling
---

## Add the JSON support module(s)

http4s-core does not include JSON support, but integration with three
popular Scala JSON libraries are supported as modules.

### Circe

The http4s team recommends circe.  Only http4s-circe is required for
basic interop with circe, but to follow this tutorial, install all three:

```scala
val http4sVersion = "{{< version "http4s.doc" >}}"

libraryDependencies ++= Seq(
  "org.http4s" %% "http4s-circe" % http4sVersion,
  // Optional for auto-derivation of JSON codecs
  "io.circe" %% "circe-generic" % "{{< version circe >}}",
  // Optional for string interpolation to JSON model
  "io.circe" %% "circe-literal" % "{{< version circe >}}"
)

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

### Argonaut

Circe is a fork of argonaut, another popular JSON library in the Scala
community.  The functionality is similar:

```scala
libraryDependencies += Seq(
  "org.http4s" %% "http4s-argonaut" % http4sVersion,
  // Optional for auto-derivation of JSON codecs
  "com.github.alexarchambault" %% "argonaut-shapeless_6.2" % "{{< version "argonaut-shapeless_6.2" >}}"
)
```

For those not ready to upgrade to argonaut-6.2, an `http4s-argonaut61`
is also available.  It is source compatible, but compiled against
Argonaut 6.1.

### Json4s

Json4s is less functionally pure than Circe or Argonaut, but older and
integrated with many Scala libraries.  It comes with two backends.
You should pick one of these dependencies:

```scala
libraryDependencies += "org.http4s" %% "http4s-json4s-native" % http4sVersion
libraryDependencies += "org.http4s" %% "http4s-json4s-jackson" % http4sVersion
```

There is no extra codec derivation library for json4s, as it generally
bases its codecs on runtime reflection.

## Sending raw JSON

Let's create a function to produce a simple JSON greeting with circe. First, the imports:

```tut:book:silent
import cats.effect._
import io.circe._
import io.circe.literal._
import org.http4s._
import org.http4s.dsl.io._
```

Then the actual code:

```tut:book
def hello(name: String): Json =
  json"""{"hello": $name}"""

val greeting = hello("world")
```

We now have a JSON value, but we don't have enough to render it:

```tut:fail
Ok(greeting).unsafeRunSync
```

To encode a Scala value of type `A` into an entity, we need an
`EntityEncoder[A]` in scope.  The http4s-circe module includes a
`org.http4s.circe` object, which gives us exactly this for an
`io.circe.Json` value:

```tut:book
import org.http4s.circe._

{'fraction_non_alphanumeric': 0.11843380500096919, 'fraction_numerical': 0.017057569296375266, 'mean_word_length': 4.48936170212766, 'pattern_counts': {'":': 2, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7025847', 'n_tokens_mistral': 1805, 'n_tokens_neox': 1686, 'n_words': 596}