Haskell Schema (or hschema) is a library with the purpose of describing data (or domains) and use that information to automatically derive serialization codecs (JSON, binary, etc.), arbitrary generators, pretty printers and much more. It is heavily inspired by the Scala library xenomorph (in fact, it is a port of the same ideas), which was introduced in the following talk at Scala World 2017:

The idea behind it is that, given a domain model you want to work with, you can use this library to build a description of it (or schema) that is totally independent of the actual code representation of the given domain model. After that, you can leverage the mechanics behind this library to generate QuickCheck generators, JSON parsers, binary codecs, etc.

Deriving Generic from your data and deriving your encoders from there seems pretty reasonable, and it's usually very concise, isn't it? But there is a problem with that, usually the data that you are going to be serializing over the wire (that's why you need your JSON, binary, etc. codecs) forms part of your public protocol. That means that every time you modify one of those data items, you are in danger of breaking your compatibility.

On top of that, what about supporting two versions of your protocol? That will get hairy quite quickly. By defining the schema separated from the actual data types, you can evolve your domain model without modifying the actual schema, add a new schema version and even define migrations between them.

Haskell Schema is distributed as a set of packages that together provide a cohesive set of features:

• hschema: This is the core package, defining the base building pieces
• hschema-aeson: This is a package that provides JSON encoding and decoding using Aeson.
• hschema-quickcheck: This package will provide with QuickCheck generators based on our schema.
• hschema-prettyprinter: This package brings pretty priting utilities.

In the following example we are going to make use of all those packages.

Let's start by defining a some data types alongside some lenses:

{-# LANGUAGE LambdaCase #-} {-# LANGUAGE OverloadedStrings #-} {-# LANGUAGE TypeFamilies #-} import Control.Lens import Data.Time (UTCTime) data Role = UserRole UserRole | AdminRole AdminRole deriving (Eq, Show) data UserRole = UserRole' deriving (Eq, Show) data AdminRole = AdminRole' { department :: String, subordinateCount :: Int } deriving (Eq, Show) _UserRole :: Prism' Role UserRole _UserRole = prism' UserRole $ \case UserRole x -> Just x _ -> Nothing _AdminRole :: Prism' Role AdminRole _AdminRole = prism' AdminRole $ \case AdminRole x -> Just x _ -> Nothing data Person = Person { personName :: String, birthDate :: Maybe UTCTime, roles :: [Role] } deriving (Eq, Show)

Now, defining the schema for the Person data type, you define each of the fields individually (name, type and getter) and combine them using an applicative:

import Data.Convertible import qualified Data.Schema as S import Data.Schema.JSON import qualified Data.Schema.JSON.Simple as JSON utcTimeSchema :: JsonSchema UTCTime utcTimeSchema = S.alias (iso convert convert) (JSON.int :: JsonSchema Integer) personSchema :: JsonSchema Person personSchema = S.record ( Person <$> S.field "name" JSON.string (to personName) <*> S.optional "birthDate" utcTimeSchema (to birthDate) <*> S.field "roles" (S.list roleSchema) (to roles) )

The schema for the Role data type is defined as a list of alternatives alongside a prism as an accessor:

adminRole :: JsonSchema AdminRole adminRole = S.record ( AdminRole' <$> S.field "department" JSON.string (to department) <*> S.field "subordinateCount" JSON.int (to subordinateCount) ) roleSchema :: JsonSchema Role roleSchema = S.oneOf [ S.alt "user" (S.const UserRole') _UserRole , S.alt "admin" adminRole _AdminRole ]

Once you have defined the schema, by proving an instance for the HasSchema typeclass, you'll get JSON decoders, encoders, generators, etc. for free right away.

import Data.Schema (HasSchema(..)) instance HasSchema Person where type PrimitivesOf Person = JsonType getSchema = personSchema

There is also built-in support for pretty printing schemas:

import Data.Schema.PrettyPrint putSchema' personSchema

That will produce an output similar to the following:

* roles :: [ - user - admin * subordinateCount :: Number * department :: Text ] * birthDate ?:: Number * name :: Text 

Not happy with that? What about a pretty printer based on the given schema? Just use the prettyPrinter function, which will return you a a -> IO () function that you can use to print your data types:

pprintPerson :: Person -> IO () pprintPerson = prettyPrinter' personSchema

All thanks to Kris Nuttycombe for his excellent work in xenomorph, this project would be have been impossible without his work.