tethys-json/tethys

Tethys is a high-performance, AST-free JSON serialization library for Scala that supports versions 2.12, 2.13, and 3. It provides a token-based API for low-level control and leverages macro-based derivation for automatic or semi-automatic handling of case classes, sealed traits, and enums. The system integrates with Jackson for backend processing and offers built-in support for standard collections, Java time types, and popular libraries like Cats and Enumeratum.

15 changes.

This period marks the initial release of the Tethys JSON library, establishing its AST-free architecture with support for Scala 2.13 and 3. The work focused on restructuring the core API around explicit JsonReader and JsonWriter traits, introducing token-based parsing and writing capabilities, and implementing strict mode validation with improved error reporting.

14 changes.

This period focused on modernizing the library for Scala 3 by replacing legacy derivation mechanisms with a new macro-based system using Mirrors and configurable builders. It also expanded ecosystem support by adding a Jackson backend, integrating with Circe and Json4s ASTs, and providing serialization support for Cats, Enumeratum, and Refined types.

This change introduces new modules for the Circe and Json4s JSON libraries within the AST layer. For Circe, it adds \CirceSupport\ (including a \JsonNumberHack\ for number serialization) and a package object to provide \JsonReader\ and \JsonWriter\ instances for Circe's \Json\ and \JsonObject\ types, along with corresponding tests. Similarly, for Json4s, it adds \Json4sSupport\ and a package object to provide readers and writers for Json4s AST types (such as \JValue\, \JObject\, \JArray\, etc.), accompanied by tests verifying the serialization and deserialization of these types.

modules/ast · high confidence

The integrations module now includes new readers and writers for several popular Scala libraries. For Cats, it adds support for NonEmptyList, NonEmptyVector, NonEmptySet, NonEmptyChain, and Chain, including Scala 2.12/2.13/3 specific implementations for NonEmptySet. For Enumeratum, it provides automatic JSON serialization for standard enums, key enums, and value enums (String, Int, Long, Short) via the TethysEnum, TethysKeyEnum, and TethysValueEnum traits. For Refined, it adds support for refined types (e.g., PosInt, IPv4) by validating constraints during deserialization and unwrapping during serialization.

modules/integrations · high confidence

The core library now includes default serialization support for a wide range of Scala and Java types. Users can now directly serialize primitive types (Int, Long, Byte, Short, Double, Float, Boolean, Char), their Java wrapper equivalents, and big numbers (BigDecimal, BigInteger). Support has also been added for collections (Iterable, Map), Option, Either, UUID, and Java 8 date/time classes (Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime). This eliminates the need for users to manually define implicit writers for these common types.

modules/core/src/main/scala/tethys/writers/instances · high confidence

The library now includes a new \CollectionBuilder\ component in the Scala 3 compatibility layer, enabling serialization of standard Scala collection types (such as \Iterable\ and \Map\) via compile-time macros. This addition provides the necessary infrastructure for handling collection serialization within the Scala 3 environment.

modules/core/src/main/scala-3/tethys/compat · high confidence

The core module now includes built-in writers for serializing Java time types (Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime) and UUIDs as JSON keys. This is achieved through the new KeyWriter trait and its implicit instances, allowing these types to be used directly as keys in JSON objects without requiring custom serialization logic.

modules/core/src/main/scala/tethys/writers · high confidence

The Scala 3 derivation module now supports configurable JSON serialization and deserialization. Users can apply field naming transformations (such as camelCase, snake\_case, or kebab-case) via the new \FieldStyle\ enum and \JsonConfiguration\ trait. Additionally, the library introduces dedicated readers and writers for Scala 3 enums, allowing them to be serialized as either their string names (\StringEnumJsonReader/Writer\) or their ordinal values (\OrdinalEnumJsonReader/Writer\), with the ability to customize the string representation.

modules/core/src/main/scala-3/tethys · high confidence

This change introduces the Tethys library, an AST-free JSON library for Scala, establishing the initial project structure and documentation. It adds support for Scala 2.13 and Scala 3, including specific quick-start guides and code examples for both versions. The release includes core JSON reading and writing capabilities, manual instance building via \contramap\/\map\, and derivation support for case classes and sealed traits. Configuration for build tools (SBT, Scalafmt) and CI/CD (GitHub Actions) is also established.

(repo-wide) · high confidence

The macro-derivation module now exposes two new package objects, \tethys.derivation.auto\ and \tethys.derivation.semiauto\, which extend \AutoDerivation\ and \SemiautoDerivation\ respectively. This provides users with dedicated entry points for automatic and semi-automatic JSON derivation, separating these capabilities from other derivation modes.

modules/macro-derivation/src/main/scala · high confidence

The benchmark suite has been reworked to include dedicated benchmarks for multiple JSON libraries (tethys-jackson, circe, json4s, play-json, spray-json, zio-json, and handwritten implementations) and now supports both Scala 2.13 and Scala 3. The benchmarks measure parsing and writing throughput across various data sizes (128b to 32mb) and include a tool to generate performance charts and markdown reports from JMH results.

modules/benchmarks/src · high confidence

This change adds the Scala 2-specific macro derivation components for the Tethys JSON library, including \AutoDerivation\ and \SemiautoDerivation\ traits, a builder DSL for defining \ReaderBuilder\ and \WriterBuilder\ schemas, and supporting utilities like \FieldStyle\ for naming conventions. These files provide the foundational macros and type-safe builders that enable automatic or semi-automatic generation of JSON serialization and deserialization logic for Scala 2.

modules/macro-derivation/src/main/scala-2 · high confidence

The core module now exposes a new token-based abstraction for JSON processing, introducing \Token\ and \TokenNode\ sealed traits with specific implementations for values, structures, and primitives (including \Byte\). This enables low-level JSON manipulation via the \jsonAsTokensList\ extension method on strings, which converts JSON text into a list of \TokenNode\ objects, and the inverse \tokensAs\ method to read typed values from token sequences. Additionally, a \RawJson\ case class is added with implicit readers and writers, allowing users to pass through raw JSON strings without parsing or formatting overhead.

modules/core/src/main/scala/tethys/commons · high confidence

The core module now exposes a new token-based writing infrastructure, introducing the \TokenWriter\ trait, its \TokenWriterProducer\, and the \SimpleTokenWriter\ implementation. This allows users to construct JSON structures via a stream of discrete tokens (such as array/object starts, field names, and typed values like Byte, Short, Int, Long, Double, etc.) rather than relying solely on high-level object mapping. The \SimpleTokenWriter\ buffers these tokens in memory and includes an extension method \asTokenList\ for converting objects into a list of token nodes, while also providing a mechanism to enable raw JSON support via \withRawJsonSupport\.

modules/core/src/main/scala/tethys/writers/tokens · high confidence

The backend module now includes a new Jackson-based implementation for JSON reading and writing, introducing \JacksonTokenIterator\ and \JacksonTokenWriter\ to bridge the library's token-based API with Jackson's \JsonParser\ and \JsonGenerator\. This change adds implicit producers for standard and pretty-printed JSON output via \tethys.jackson\ and \tethys.jackson.pretty\ packages, enabling users to serialize and deserialize JSON using Jackson's underlying engine while maintaining the library's token-stream abstraction. Tests verify correct handling of primitive types, nested structures, and raw JSON preservation.

modules/backend · high confidence

The core module now includes Scala 2.12-specific compatibility files to support the derivation system on this version. This includes a \CollectionBuilder\ trait that wraps \CanBuildFrom\ for constructing collections, alongside empty \JsonObjectWriterDerivation\ and \JsonReaderDerivation\ traits that serve as placeholders for Scala 2.12 derivation logic.

modules/core/src/main/scala-2.12 · high confidence

This change introduces new source files for the Scala 2.13+ compatibility layer, specifically adding \CollectionBuilder.scala\ which provides macro-based implicit conversions for \IterableFactory\ and \MapFactory\ to support efficient collection building. It also adds empty placeholder traits \JsonObjectWriterDerivation\ and \JsonReaderDerivation\ within the \tethys.derivation\ package, establishing the structural foundation for configurable derivation logic on this platform.

modules/core/src/main/scala-2.13+ · high confidence

The core tethys API has been refactored to introduce dedicated \JsonReader\ and \JsonWriter\ traits, replacing the previous implicit-based structure. This change adds a \JsonObjectWriter\ for structured object writing, an \emap\ method on \JsonReader\ for error-aware mapping, and a \JsonStreaming\ utility for direct token-level copying. Users will now interact with a more explicit reader/writer model, with new extension methods like \asJson\ and \jsonAs\ provided in the package object for convenient conversion.

modules/core/src/main/scala/tethys · high confidence

The \tethys.derivation.builder\ package now provides deprecated compatibility shims for \ReaderBuilder\, \WriterBuilder\, \ReaderDerivationConfig\, \WriterDerivationConfig\, \ReaderDescription\, and \WriterDescription\. These legacy types and configurations are marked for removal and users should migrate to the corresponding \tethys.ReaderBuilder\ and \tethys.WriterBuilder\ APIs to ensure future compatibility.

modules/core/src/main/scala-3/tethys/derivation/builder · high confidence

The \AutoDerivation\ and \SemiautoDerivation\ traits in the Scala 3 macro-derivation module now mark their existing methods (such as \jsonWriter\ and \jsonReader\) as deprecated. Users are instructed to migrate to the new \JsonObjectWriter.derived\, \JsonReader.derived\, or the \derives\ keyword for automatic derivation. The diff also introduces compile-time errors for unsupported old enum derivation patterns, guiding users toward \StringEnumWriter.derived\, \OrdinalEnumWriter.derived\, or direct usage of \WriterBuilder\/\ReaderBuilder\ for complex configurations.

modules/macro-derivation/src/main/scala-3 · high confidence

The core JSON reading API has been refactored to introduce a new \JsonReaderBuilder\ that supports strict mode validation, ensuring that unexpected JSON fields cause errors rather than being silently ignored. Error reporting has been enhanced with the introduction of \FieldName\ to track the full path of nested fields during parsing, and \ReaderError\ now includes a specific reason for failures and propagates the underlying cause. Additionally, new \KeyReader\ implementations have been added to support parsing UUIDs and various Java 8 date/time types (Instant, LocalDate, LocalDateTime, OffsetDateTime, ZonedDateTime) from JSON keys.

modules/core/src/main/scala/tethys/readers · high confidence

The \modules/core/src/main/scala/tethys/readers/instances\ package has been restructured to improve performance and code organization. Primitive readers (Boolean, String, Number, Byte, Short, Int, Long, Float, Double, Char, BigDecimal, BigInt) and their Java counterparts are now explicitly defined in \AllJsonReaders.scala\ and backed by optimized implementations in \PrimitiveReaders.scala\. New specialized readers have been added for \Iterable\, \Map\, and \Option\ types, including specific optimizations for primitive collections and maps. The internal derivation logic now utilizes \SimpleJsonReader\ and \SimpleJsonReaderNoDefault\ classes to handle field extraction, supporting both strict and non-strict modes, while \SelectingJsonReader\ variants manage polymorphic selection. This change replaces previous implicit-based derivation patterns with a more explicit, trait-based hierarchy (\LowPriorityJsonReaders\, \IterableReaders\, \MapReaders\, \OptionReaders\) to resolve implicits more efficiently.

modules/core/src/main/scala/tethys/readers/instances · high confidence

The core token reading mechanism has been restructured to use a new \TokenIterator\ trait and a \QueueIterator\ implementation that processes tokens via an immutable queue of \TokenNode\ objects. This change introduces specific typed node wrappers (such as \ByteValueNode\, \ShortValueNode\, etc.) and enforces strict type checking during value extraction, throwing a \WrongTokenError\ if the expected node type does not match the actual token. The iterator now supports expression skipping and collection through a \CopySupport\ interface, replacing the previous direct token handling logic.

modules/core/src/main/scala/tethys/readers/tokens · high confidence

The Scala 3 JSON derivation implementation has been replaced with a new macro-based system that leverages Scala 3 Mirrors for automatic derivation. This change introduces \WriterBuilder\ and \ReaderBuilder\ as the primary configuration mechanisms, replacing the legacy \WriterDerivationConfig\ and \ReaderDerivationConfig\ (now deprecated). The new system supports configurable field styles, strict mode merging from \JsonConfiguration\, and improved handling of complex sum types and opaque types. It also adds specific utilities for enum derivation via \EnumCompanion\.

modules/core/src/main/scala-3/tethys/derivation · high confidence

Added Scala 3 derivation test suite; Added Scala 3 derivation test suite; Added test coverage for Scala 2.13+ macro derivation; Added tests for default readers, JsonReaderBuilder, and token iteration; Added tests for default writers and SimpleJsonObjectWriter.

This release updates the project's build configuration to use Scala 2.12.21, 2.13.18, and 3.3.8. It upgrades several key library dependencies: circe-core to 0.14.15, json4s-ast to 4.0.7, cats-core to 2.13.0, enumeratum to 1.9.0, and scalatest to 3.2.20. The build also configures cross-compilation for Scala 2.12, 2.13, and 3, and introduces separate Jackson backend modules (jackson-212 through jackson-218) to support various Jackson versions.

(dependencies) · high confidence

The project's build configuration has been updated to use sbt version 1.11.7, and the plugin set now includes sbt-jmh 0.4.8 for benchmarking, sbt-scalafmt 2.5.6 for formatting, and sbt-ci-release 1.12.0 for release automation. Additionally, a new Scala file \JsonReaderBuilderGenerator.scala\ was added to the \project\ directory, providing a scaffolded generator object intended to produce \JsonReaderBuilder.scala\ within the \readers\ package.

project · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 65.

• Code Health 94
• Architecture 100
• Maturity 56
• Readiness 67
• Security 65

• 300 commits — 271 feature/other, 29 fixes

• (repo) — 100 commits
• (root) — 86 commits
• modules/core — 41 commits
• .github/workflows — 23 commits
• project/plugins.sbt — 20 commits
• modules/macro-derivation — 12 commits
• project/build.properties — 7 commits
• modules/integrations — 4 commits
• modules/cats — 2 commits
• .github/dependabot.yml — 1 commit
• modules/ast — 1 commit
• modules/backend — 1 commit
• modules/benchmarks — 1 commit
• modules/refined — 1 commit

• fix: Add tests for scala3 enum derivation and fix writer derivation for scala3 enums (#224)
• fix: Deprecate JsonReaderDefaultValue. Add defaultValue directly to JsonReader. Fixes #361
• fix: Merge pull request #359 from Ganddalf/fix-github-pages
• fix: Merge pull request #374 from road21/fix-warn-inline-new-class-duplication
• fix: Merge pull request #400 from road21/fix-bug-wrong-json
• fix: Merge pull request #428 from TheBugYouCantFix/typo-fixes
• fix: fix build.sbt formatting
• fix: fix cats version
• fix: fix collect defaults and add tests
• fix: fix compilation
• fix: fix discriminator selection for opaque types
• fix: fix field style compatibility
• fix: fix field style compatibility
• fix: fix github-pages
• fix: fix jsonReader for annotated fields
• fix: fix reader message on missing fields
• fix: fix scala.yml
• fix: fix warn about anon class duplicaton
• fix: fix: propagate cause in ReaderError.wrongJson
• fix: fix: proper scala3 version in workflows
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

tethys-json/tethys was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.