Lightweight pure data validation based on Applicative and Selective functors.

Validation allows to accumulate all errors instead of short-circuting on the first error so you can display all possible errors at once.

Common use-cases include:

1. Validating each input of a form with multiple inputs.
2. Performing multiple validations of a single value.

Validation provides modular and composable interface which means that you can implement validations for different pieces of your data independently, and then combine smaller parts into the validation of a bigger type. The below table illustrates main ways to combine two Validations:

In other words, instances of different standard typeclasses provide various semantics which can be useful in different use-cases:

1. Semigroup: accumulate both Failure and Success with <>.
2. Monoid: Success that stores mempty.
3. Functor: change the type inside Success.
4. Bifunctor: change both Failure and Success.
5. Applicative: apply function to values inside Success and accumulate errors inside Failure.
6. Alternative: return the first Success or accumulate all errors inside Failure.
7. Selective: choose which validations to apply based on the value inside.

This section contains the typical Validation usage example. Let's say we have a form with fields where you can input your login information.

>>> :{
data Form = Form
    { formUserName :: !String
    , formPassword :: !String
    }
:}

This Form data type can represent values of some text fields on the web page or inside the GUI application. Our goal is to create a value of the custom User data type from the Form fields.

First, let's define our User type and additional newtypes for more type safety.

>>> :{
newtype UserName = UserName
    { unUserName :: String
    } deriving newtype (Show)
:}

>>> :{
newtype Password = Password
    { unPassword :: String
    } deriving newtype (Show)
:}

>>> :{
data User = User
    { userName     :: !UserName
    , userPassword :: !Password
    } deriving stock (Show)
:}

We can easily create a User from the Form in the unsafe way by wrapping each form field into the corresponding newtype:

>>> :{
unsafeUserFromForm :: Form -> User
unsafeUserFromForm Form{..} = User
    { userName     = UserName formUserName
    , userPassword = Password formPassword
    }
:}

However, this conversion is unsafe (as name suggests) since Form can contain invalid data. So, before creating a User we want to check whether all Form fields satisfy our preconditions. Specifically:

1. User name must not be empty.
2. Password should be at least 8 characters long.
3. Password should contain at least 1 digit.

Validation offers modular and composable way of defining and outputting all validation failures which means:

1. Modular: define validation checks for different fields independently.
2. Composable: combine smaller validations easily into a validation of a bigger type.

Before implementing Form validation, we need to introduce a type for representing our validation errors. It is a good practice to define all possible errors as a single sum type, so let's go ahead:

>>> :{
data FormValidationError
    = EmptyName
    | ShortPassword
    | NoDigitPassword
    deriving stock (Show)
:}

With Validation we can define checks for individual fields independently and compose them later. First, let's start with defining validation for the name:

>>> :{
validateName :: String -> Validation (NonEmpty FormValidationError) UserName
validateName name = UserName name <$ failureIf (null name) EmptyName
:}

You can notice a few things about this function:

1. All errors are collected in NonEmpty, since we want to have guarantees that in case of errors we have at least one failure.
2. It wraps the result into UserName to tell that validation is passed.

Let's see how this function works:

>>> validateName "John"
Success "John"
>>> validateName ""
Failure (EmptyName :| [])

Since Validation provides modular interface for defining checks, we now can define all validation functions for the password separately:

>>> :{
validateShortPassword :: String -> Validation (NonEmpty FormValidationError) Password
validateShortPassword password = Password password <$
    failureIf (length password < 8) ShortPassword
:}

>>> :{
validatePasswordDigit :: String -> Validation (NonEmpty FormValidationError) Password
validatePasswordDigit password = Password password <$
    failureUnless (any isDigit password) NoDigitPassword
:}

After we've implemented validations for different Form fields, it's time to combine them together! Validation offers several ways to compose different validations. These ways are provided via different instances of common Haskell typeclasses, specifically:

• Semigroup
• Alternative
• Applicative

Semigroup allows combining values inside both Failure and Success but this requires both values to implement the Semigroup instance. This doesn't fit our goal, since Password can't have a reasonble Semigroup instance.

Alternative returns first Success or combines all Failures. We can notice that Alternative also doesn't work for us here.

In our case we are interested in collecting all possible errors and returning Success only when all checks are passed. Fortunately, Applicative is exactly what we need here. So we can use the *> operator to compose all checks for password:

>>> :{
validatePassword :: String -> Validation (NonEmpty FormValidationError) Password
validatePassword password =
    validateShortPassword password *> validatePasswordDigit password
:}

Let's see how it works:

>>> validatePassword "abcd"
Failure (ShortPassword :| [NoDigitPassword])
>>> validatePassword "abcd1"
Failure (ShortPassword :| [])
>>> validatePassword "abcd12345"
Success "abcd12345"

The validation library provides several convenient combinators, so you can write the password check in a shorter way:

validatePassword :: String -> Validation (NonEmpty FormValidationError) Password
validatePassword = fmap Password . validateAll
    [ (`failureIf`     ShortPassword)   . (< 8) . length
    , (`failureUnless` NoDigitPassword) . any isDigit
    ]

After we've implemented validations for all fields, we can compose them together to produce validation for the whole User. As before, we are going to use the Applicative instance:

>>> :{
validateForm :: Form -> Validation (NonEmpty FormValidationError) User
validateForm Form{..} = User
    <$> validateName formUserName
    <*> validatePassword formPassword
:}

And it works like a charm:

>>> validateForm (Form "" "")
Failure (EmptyName :| [ShortPassword,NoDigitPassword])
>>> validateForm (Form "John" "abc")
Failure (ShortPassword :| [NoDigitPassword])
>>> validateForm (Form "Jonh" "qwertypassword")
Failure (NoDigitPassword :| [])
>>> validateForm (Form "Jonh" "qwertypassword123")
Success (User {userName = "Jonh", userPassword = "qwertypassword123"})

When using Validation, we often work with the NonEmpty list of errors, and those lists will be concatenated later.

The following functions aim to help with writing more concise code.

For example, instead of (perfectly fine) code like:

>>> :{
validateNameVerbose :: String -> Validation (NonEmpty String) String
validateNameVerbose name
    | null name = Failure ("Empty Name" :| [])
    | otherwise = Success name
:}

one can write simply:

>>> :{
validateNameSimple :: String -> Validation (NonEmpty String) String
validateNameSimple name = name <$ failureIf (null name) "Empty Name"
:}

Validation is usually compared to the Either data type due to the similarity in structure, nature and use case. Here is a quick table you can relate to, in order to see the main properties and differences between these two data types:

Comparison in example

For the sake of better illustration of the difference between Either and Validation, let's go through the example of how parsing is done with the usage of these types.

Our goal is to parse two given Strings and return their sum in case if both of them are valid Ints. If any of the inputs is failing to be parsed we should return the ParseError which we are introducing right now:

>>> :{
newtype ParseError = ParseError
    { nonParsedString :: String
    } deriving stock (Show)
:}

Let's first implement the parsing of single input in the Either context:

>>> :{
parseEither :: String -> Either ParseError Int
parseEither input = case readMaybe @Int input of
    Just x  -> Right x
    Nothing -> Left $ ParseError input
:}

And the final function for Either looks like this:

>>> :{
parseSumEither :: String -> String -> Either ParseError Int
parseSumEither str1 str2 = do
    let x = parseEither str1
    let y = parseEither str2
    liftA2 (+) x y
:}

Let's now test it in action.

>>> parseSumEither "1" "2"
Right 3
>>> parseSumEither "NaN" "42"
Left (ParseError {nonParsedString = "NaN"})
>>> parseSumEither "15" "Infinity"
Left (ParseError {nonParsedString = "Infinity"})
>>> parseSumEither "NaN" "infinity"
Left (ParseError {nonParsedString = "NaN"})

Note how in the case of both failed parsing we got only the first NaN.

To finish our comparison, let's implement the same functionality using Validation properties.

>>> :{
parseValidation :: String -> Validation (NonEmpty ParseError) Int
parseValidation input = case readMaybe @Int input of
    Just x  -> Success x
    Nothing -> failure $ ParseError input
:}

>>> :{
parseSumValidation :: String -> String -> Validation (NonEmpty ParseError) Int
parseSumValidation str1 str2 = do
    let x = parseValidation str1
    let y = parseValidation str2
    liftA2 (+) x y
:}

It looks almost completely identical except for the resulting type — Validation (NonEmpty ParseError) Int. But let's see if they behave the same way:

>>> parseSumValidation "1" "2"
Success 3
>>> parseSumValidation "NaN" "42"
Failure (ParseError {nonParsedString = "NaN"} :| [])
>>> parseSumValidation "15" "infinity"
Failure (ParseError {nonParsedString = "infinity"} :| [])
>>> parseSumValidation "NaN" "infinity"
Failure (ParseError {nonParsedString = "NaN"} :| [ParseError {nonParsedString = "infinity"}])

As expected, with Validation we got all parse Failures we received on the way.

Combinators

We are providing several functions for better integration with the Either related code in this section.