Validation generally takes the form of a -> Either f b where:

a

Some unvalidated type.

b

Some validated type.

f

Some failure type.

Consider the following example:

 data MyFailures = EmptyEmailAddress | MalformedEmailAddress
 validateEmailAddress :: String -> Either MyFailures EmailAddress
 

In this case:

• a ~ String
• b ~ EmailAddress
• f ~ MyFailures

The transformation from a to b is important and provides a type safe way to prove that validation was successful. However, rather than using the Either type, this library uses the Proof type. A Proof represents either a validated type or a collection of failures. Notice, we use the term validation failures instead of errors to differentiate between validation and error handling. The reason we use the Proof type is because it has a custom Applicative instance that will be helpful later.

The Invalid constructor takes a list of global failures and a map of field failures. Field failures are useful for identifying a specific field in a record that is invalid. Fields are identified using a list of Name types. There are two ways to create this type: the TemplateHaskellQuotes extension and the mkName function.

Using the TemplateHaskellQuotes language extension, you can easily create Names using a special syntax. For a records like:

data User = User { emailAddress :: String }

The name can be retrieved by referencing the name with a single quote in front:

let name = 'emailAddress

This allows for the consistant and type safe generation of names. This method does generate a fully qualified name that includes the module name. The base name can be accessed using the nameBase function. This extension is considered safe Haskell while the TemplateHaskell extension is not. See https://ghc.gitlab.haskell.org/ghc/doc/users_guide/exts/template_haskell.html#syntax for details.

Another approach is to use the mkName function. This allows field names to be generated for non-record types. However, it does require managing magic strings.

To finish our discussion on the Proof type, the reason the key is a list of names is because of subfields. Consider a record like this:

 data Contact = Contact { phoneNumber :: String }

 data User
   = User
   { username :: String
   , contact :: Contact
   }
 

In this case, validating the User type requires validating the contact field which is a Contact. In that case, the key would need to identify that the phoneNumber field is a subfield of contact. The key would look like this:

['contact, 'phoneNumber]

This library uses composable validations. As such, we need a type that carries information about the thing being validated. Specifically, we need a type to carry its value and, optionally, its name.

A value with a name is a field and will be used to create field failures. A value without a name will be used to create global failures. This is accomplished using the ValueCtx type.

The withField and withValue functions are used to create these types and perform validation at the same time. These functions save the effort of wrapping and unwrapping values with the ValueCtx type.

Validating primitives is a special case because the validated type and unvalidated type are often the same. An email address is just a specially formatted string, so both the unvalidated email address and the validated one have the same types. To get around this, you can wrap a primitive in a `newtype`, hide the constructor, and create a smart constructor that validates the input. This allows for a kind of type safety known as `correct by construction`. Consider the following example.

 module Primitives
 ( MyFailures
 , EmailAddress -- the constructors are not exported
 , mkEmailAddress
 ) where

 data MyFailures = EmptyEmail |

 mkEmailAddress :: String -> Proof MyFailures EmailAddress
 mkEmailAddress s = fromVCtx $ do              -- (1)
   v <- withValue s $ \v -> do                 -- (2)
     isNotNull EmptyEmail v                    -- (3)
     disputeWithFact InvalidEmail (elem '@') v -- (4)
   return $ EmailAddress v                     -- (5)
 

Starting with line (2), the withValue function is used to create a ValueCtx using string passed into the function. The lambda function that follows takes the ValueCtx and runs it through several validators using `do` syntax. This is possible because VCtx has a Monad instance.

Line (1) transforms the result from a VCtx to a Proof as discussed above.

Line (3) and (4) demonstrate both a general validator and a custom validator. These will be covered in more detail later.

Line (5) constructs the EmailAddress type and returns it. If any validation failures occur before this point, an Invalid result is generated instead of the EmailAddress.

It is important to note that no instances should be created for the EmailAddress type that allow construction. This includes the FromJSON type class from the aeson library.

In general, validating complex types works the same way as validating primitives. It starts with an unvalidated type that is transformed into a validated type. These unvalidated types are often called "view models". View models should be transformed into models when they are validated. So, like primitives, validating complex types should have the form validate :: a -> Proof f b.

For complex types, this can be accomplished with the 'Validatable f a b' type class. This type class takes 3 parameters: the failure type, the view model type, and the final model type. It requires the implementation of a single function: validation. Then the validate function can be used to perform the actual validation. Consider the following example:

 -- unvalidated type
 data UserCreatableVM
   = UserCreatableVM
   { userCreatableVMEmailAddress         :: String
   , userCreatableVMConfirmEmailAddress  :: String
   , userCreatableVMPassword             :: String
   , userCreatableVMConfirmPassword      :: String
   , userCreatableVMName                 :: Maybe String
   }

 -- validated type
 data UserCreatable
   = UserCreatable                                                                                     -- (1)
   { userCreatableEmailAddress :: EmailAddress
   , userCreatablePassword     :: Password
   , userCreatableName         :: Maybe Name
   }

 instance Validatable MyFailureType UserCreatableVM UserCreatable where                                -- (2)
   validation u =
     let ve = withField 'userCreatableVMEmailAddress (userCreatableVMEmailAddress u) $
           refuteWithProof mkEmailAddress                                                              -- (3)
         vce = withField 'userCreatableVMConfirmEmailAddress (userCreatableVMConfirmEmailAddress u) $
           \ce -> refuteWithProof mkEmailAddress ce
           >>= isMatch MismatchedEmail ve                                                              -- (4)
         vp = withField 'userCreatableVMPassword (userCreatableVMPassword u) $
           refuteWithProof mkPassword
         vcp = withField 'userCreatableVMConfirmPassword (userCreatableVMConfirmPassword u) $
           \ce -> refuteWithProof mkPassword ce
           >>= isMatch MismatchedPassword vp
         vn = optional (userCreatableVMName u) $ \n ->
             withField 'userCreatableVMName n $ refuteWithProof mkName
         otherCheck = withValue u nameNotInPassword
     in pure UserCreatable <*> ve <*> vp <*> vn <! vce <! vcp <! otherCheck                            -- (5)
   where nameNotInPassword = ...
 

The final model does not have all of the same fields on line (1). The confirmation fields were removed because they serve no purpose beyond validation.

The validation function is implemented much like the smart constructors in the previous section. However, it is using the withField function instead of withValue. In addition, there is no call to fromVCtx because validation is expected to return a VCtx. Another function, validate, will use these validations to produce a Proof.

On line (2), the Validatable instance is declared with an application specific failure type. The second and third parameter are the view model and final model types. This represents the transformation from the unvalidated type to the validated types.

On line (3), there is a call to refuteWithProof which validates and constructs a primitive using the smart constructor from the previous example. Line (4) uses the isMatch function to prove that the email address and confirm email address fields match. The function accepts a VCtx to match against making it very easy to compare validated field.

Finally, line (5) is a bit interesting. It constructs the final type using applicative syntax. It uses the applicative instance on VCtx to construct the final type. If all of the parameters are valid, the expression returns a valid UserCreatable. However, if any of the parameters are invalid, the whole expression becomes invalid and contains every failure from every field. This creates the aggregated result.

There is also a call to the '(<!)' function. This function is read as aggregateFailures. In English, it takes the failures from the second parameter, if any, and adds them to the first. This allows the aggregation of failures from fields that are not included in the final type.

Refuting a value stops all validation efforts on the value. This means that any future failures that could have been detected will not. Dispute, on the other hand, will allow validation to continue. So, why should one be chosen over the other?

First, we have to look at how validation works. Validation transforms values from an unvalidated type to a validated type. So, when a value is being passed through a validation chain, it is being transformed. If a validation fails, the transform fails too; there is no way around this. The new value cannot be retrieved from the validation if it failed.

Consider a Maybe String value that is required and must be at least 3 characters long. First, the value would pass through the isRequired validator. If the value is a Just a, validation succeeds and the value a is passed to the next validator which checks its length. If the value is a Nothing, it is not possible to check its length. Therefore, the validation must be refuted. A refuted value results in an invalid Proof but stops the execution of any further validation.

Now, consider an Int value that must be greater than 2 and even. First, the value would pass though the minValue validator. If the value is greater than 2, validation succeeds and the isEven validator is called. If the value is 2 or less, the validation fails. However, rather than fail completely, the next validator can just use the same value that was passed into the minValue validator. In that case, the validator should dispute the value so that the next validator can be run. This will still result in an invalid Proof but allows for more failures to be detected.

In general, if a validator has the form a -> Either f b, a failure must be refuted because they transform the value. If it has the form a -> Maybe f, it should be disputed because it does not transform the value.