Argonaut: a JSON library built for functional Scala

What Argonaut is for: JSON as a value, not a map

Argonaut is a JSON library for Scala, providing a rich library for parsing, printing and manipulation as well as convenient codecs for translation to and from Scala data types.

The design commitment is in the word functional, and it shows in the whole shape of the API. JSON is not modelled as a mutable map of strings to values that you walk and mutate. It is a data type with cases, and the operations on it return new values. The library belongs to the same family as circe, which is what a Scala developer who reaches for Argonaut is usually comparing it against.

The codecs are the part that determines whether the library is worth adopting. A codec is a pair of a decoder and an encoder, so a case class can be read from JSON and written back to it without hand written extraction of each field, and the same mechanism means a failed decode is a value you can pattern match on rather than an exception. For a service with a defined API boundary, that is the whole point of using a JSON library rather than reaching for a mapper.

The provenance explains some of the shape. Argonaut was initially developed to support products at Ephox, who have now kindly relinquished control to the community, and the library was open-sourced under a BSD License, drawing users, support and improvements from a number of contributors. The repository is a single core module plus a set of integration modules, which is the layout you would expect from a library that grew by accretion around a stable core.

The module layout: one core and four integrations

The top level entries tell you how the library is put together, and the pattern is clear. There is `argonaut/`, which is the core, and then `argonaut-cats/`, `argonaut-jawn/`, `argonaut-monocle/` and `argonaut-scalaz/`, each of which is a separate module.

Each of those four integrates Argonaut with a specific library. The scalaz module pairs it with Scalaz, and the README states the version constraints: the 6.2.x releases support Scala `2.11.*`, `2.12.*` and `2.13.*` with scalaz `7.2.*`, while the 6.3.x releases support Scala `2.12.*`, `2.13.*` and `3.x` with scalaz `7.3.*`. The cats module is the same idea for Typelevel cats, the monocle module for the Scala optics library, and jawn is the JSON parser that Argonaut can sit on top of, which matters if you already have jawn in your stack and want to avoid parsing JSON twice.

The build is sbt based, with a `build.sbt` at the root, a `project/` directory for the build definition, a `version.sbt` for the version, and an `sbt` launcher script checked in. A `shell.nix` and an `.envrc` are present, so a Nix based development environment is set up, and `.scalafmt.conf` means the formatting is enforced by scalafmt rather than by hand. The `argonaut-benchmark/` directory is a benchmark module, and `notes/` holds design notes.

The `CONTRIBUTORS` file and a `COPYING` file alongside `LICENCE` are worth a note, because the licensing in this repository is not entirely straightforward, which the next section covers.

The licence question: BSD3 in the README, something else in the file

The README says Argonaut is licenced under BSD3 and points at `LICENCE`, and the provenance section says the library was open-sourced under a BSD License. The repository's own licence field, however, is recorded as a custom licence that GitHub cannot classify, with the LICENSE file as the authority. There is a `LICENCE` file and a separate `COPYING` file at the root, and the two names suggest that more than one set of terms is in play.

For a team that matters more than it sounds. The README's BSD3 statement may describe the core library's history, while the repository as a whole now carries terms that the classifier cannot read, and a build that pulls in several modules at once may not be covered uniformly. The honest procedure is to read the `LICENCE` file in the repository root and work out from there which terms apply to the code you are actually importing, and to have whoever owns licensing in your organisation look at it.

The history is the other half of the picture. The library was developed at Ephox for its own products and then handed over to the community, and the README credits a number of contributors. That handover is a normal open source trajectory and it does not by itself create a problem, but it is the reason there are two licence-named files rather than one.

The release history is worth noting too. The listed release is v6.2.1, described as the first scala-native support, dated 2017-12-29, and the SBT snippet in the README points at version 6.3.13, so the published artefact is well past the tagged release in the repository. The last push to the tree was on 2026-10-19, so the code is being worked on even though the tag list is old.

Adding Argonaut to a build

Adding the library to a project is one line in the build definition, and the README's instruction is simply to add argonaut as a dependency. The stable coordinates are given for the Scala 3 artifact.

libraryDependencies += "io.github.argonaut-io" %% "argonaut" % "6.3.13"

The `%%` rather than `%` is sbt's Scala binary-version operator, so the same line resolves the right artifact for whichever Scala version your project targets.

The version choice then determines the ecosystem you get. The 6.2.x line supports Scala `2.11.*`, `2.12.*` and `2.13.*` with scalaz `7.2.*`, and the 6.3.x line supports Scala `2.12.*`, `2.13.*` and `3.x` with scalaz `7.3.*`. So if your project is on Scala 3, the 6.3.x line is the only one of the two that applies, and the scalaz module comes with the version bump.

The Maven Central badge points at the `argonaut_3` artifact, which is the Scala 3 build, and the README also links the Scala API docs on javadoc.io for the latest version. For usage patterns there is a separate examples directory in the repository, at `argonaut/shared/src/test/scala/argonaut/example`, linked from the README as the place to look at how the API is meant to be used.

Releasing it, and what the build looks like to a maintainer

The README documents the release process, which is short and worth reading if you are evaluating how actively the project is stewarded.

A snapshot build is a single sbt invocation.

    ./sbt +publish

A release build is the cross release task.

    ./sbt "release cross"

The `+` prefix in the publish command is sbt's cross-building operator, and `release cross` is the plugin's release task for a cross-built artifact, which matches the fact that the library publishes for several Scala versions at once.

The release task is interactive, and the README explains the prompt sequence. You enter the details for the release build number and then the subsequent build number, and it is fine to enter the original build number as the next number when you are doing a milestone or release candidate. The example given is a release version of 6.0-M3 followed by a next version of 6.0-SNAPSHOT.

That is the shape of a mature sbt project with a version scheme, an interactive release flow and a cross build matrix. It is also the shape of a project that has settled on its release conventions, which matters for someone deciding whether to depend on it: the process is documented, the versions are consistent with the Scala matrix, and the modules are separate so you take only the integrations you need.

What the README does not cover is the migration path between the 6.2.x and 6.3.x lines beyond the version matrix. If you are upgrading an existing project across that boundary, the API differences are something you will find in the code rather than in the documentation.

Editorial conclusion

Adopt Argonaut if your Scala codebase already models JSON as a sealed algebraic data type and you want codecs, a cursor style manipulator and an integration module for the effect library you already use. Do not adopt it for a mixed polyglot shop, since the ecosystem modules assume Scalaz 7.3 or a specific cats and monocle version, and the README does not list the newer Scala 3 only libraries. Before you commit, read the `LICENCE` file in the repository root rather than the BSD3 sentence in the README, because the licence field is recorded as a custom licence and the two do not obviously agree.

Frequently asked questions

Official sources

1. argonaut-io/argonaut on GitHub
2. Issues
3. README
4. Releases