seals is an experimental project by Daniel Urban, which provides tools for schema evolution and language-integrated schemata.
By using it, you will be able to
- define schemata by creating ordinary Scala datatypes;
- check the compatibility of different versions of a schema at compile time, as well as runtime;
- automatically derive serializers and deserializers for your schema-datatypes (currently only circe and scodec encoders and decoders are implemented);
- and communicate between components using different (but compatible) versions of a schema.
Since it's a fairly new project, not all of these features are implemented yet. Bugs are to be expected as well. Contributions to improve the project, and reports about issues you encounter are welcome.
seals is currently available for Scala 2.12 and 2.13. JARs are available
on Maven Central.
To use it, put this into your build.sbt (see below
for the available modules):
libraryDependencies += "dev.tauri" %% "seals-core" % "0.4.0-RC2"All releases (and commits on the master branch) are signed by key
36A8 2002 483A 4CBF A5F8 DF6F 48B2 9573 BF19 7B13.
By using seals-core, you can define a schema simply by creating an ADT:
final case class User(id: Int, name: String)An abstract representation of this schema can be retrieved by requesting
an instance of the Reified type class.
import dev.tauri.seals.Reified
Reified[User]This abstract representation is used to implement the following features.
(End users usually don't have to work with Reified directly.)
In the next version of the schema defined above, you may want to add a new field (with a default value):
final case class UserV2(id: Int, name: String, age: Int = 42)Thanks to the default value, these two versions are compatible with
each other. We can assert this by using the Compat type class:
import dev.tauri.seals.Compat
Compat[User, UserV2]If they wouldn't be compatible, we would get a compile time error
(because there would be no Compat instance available). For example,
if we define a new schema like this:
final case class UserV3(id: Int, name: String, age: Int) // no default `age`Then there will be no Compat instance available, since the schemata
are not compatible:
Compat[User, UserV3] // error: could not find implicit value for ...For a more detailed introduction to the Compat type class,
see this example.
By using the seals-plugin module (which is an sbt plugin), we can
check in our build whether our current schemata are compatible with
previously released versions. (Similarly to how MiMa checks binary
compatibility with previous versions.) For how to do this, see
this example. The plugin
is available for sbt 1.x.
If you are interested in other features (like automatic derivation of serializers, or runtime compatibility checking), at the moment the best way is to look at the examples or directly at the sources (and Scaladoc comments, and laws/tests).
The subprojects are as follows:
core: essential type classes (required)circe: automatic derivation of circe encoders and decoders (optional)scodec: automatic derivation of scodec codecs, encoders and decoders (optional)refined: support for refined typesplugin: sbt plugin for build-time compatibility checking of schema definitions (basically MiMa for schemata)checker: the schema checker used by the sbt pluginmacros: a few macros used internally bycorelaws: definitions of laws for the type classes incore(incomplete, for testing)tests: unittests (don't depend on this)examples: a few examples for using the library
seals depends on the following projects:
- shapeless provides the macros and type classes to automatically derive schemata and other type class instances for ADTs.
- Cats provides general functional programming tools which complement the Scala standard library.
- scodec-bits provides an
immutable
ByteVectordatatype. - MiMa provides some utilities for working with artifacts in
seals-plugin.
Currently there are interop modules for the following projects:
- circe provides the JSON framework for which
sealsderives encoders and decoders. - scodec provides a binary encoding/serialization framework for which
sealsderives codecs.- FS2 enables streaming encoding and decoding of data with scodec.
- refined provides refinement types, some of which are supported by
seals.
For testing, it also uses:
- ScalaTest for the unittests,
- ScalaCheck for automated property-based testing,
- and scalacheck-shapeless to generate pseudorandom ADT instances.
seals is open source software under the Apache License v2.0. For details, see the LICENSE.txt, NOTICE.txt, and AUTHORS files.