Data.Swagger.Schema.Validation

Validate JSON values with Swagger Schema.

How to use validation

This module provides helpful functions for JSON validation. These functions are meant to be used in test suites for your application to ensure that JSON respresentation for your data corresponds to schemas you're using for the Swagger specification.

It is recommended to use validation functions as QuickCheck properties (see http://hackage.haskell.org/package/QuickCheck).

Examples

>>> validateToJSON "hello"
[]

>>> validateToJSON False
[]

>>> newtype Nat = Nat Integer deriving Generic
>>> instance ToJSON Nat where toJSON (Nat n) = toJSON n
>>> instance ToSchema Nat where declareNamedSchema proxy = genericDeclareNamedSchema defaultSchemaOptions proxy & mapped.minimum_ ?~ 0
>>> validateToJSON (Nat 10)
[]
>>> validateToJSON (Nat (-5))
["value -5.0 falls below minimum (should be >=0.0)"]

Validating Maybe

Because Maybe a has the same schema as a, validation generally fails for null JSON:

>>> validateToJSON (Nothing :: Maybe String)
["expected JSON value of type SwaggerString"]
>>> validateToJSON ([Just "hello", Nothing] :: [Maybe String])
["expected JSON value of type SwaggerString"]
>>> validateToJSON (123, Nothing :: Maybe String)
["expected JSON value of type SwaggerString"]

However, when Maybe a is a type of a record field, validation takes required property of the Schema into account:

>>> data Person = Person { name :: String, age :: Maybe Int } deriving Generic
>>> instance ToJSON Person
>>> instance ToSchema Person
>>> validateToJSON (Person "Nick" (Just 24))
[]
>>> validateToJSON (Person "Nick" Nothing)
[]

JSON validation

type ValidationError = String

Validation error message.

Using ToJSON and ToSchema

validateToJSON :: forall a. (ToJSON a, ToSchema a) => a -> [ValidationError]

Validate ToJSON instance matches ToSchema for a given value. This can be used with QuickCheck to ensure those instances are coherent:

validateToJSON (x :: Int) == []

NOTE: validateToJSON does not perform string pattern validation. See validateToJSONWithPatternChecker.

validateToJSONWithPatternChecker :: forall a. (ToJSON a, ToSchema a) => (Pattern -> Text -> Bool) -> a -> [ValidationError]

Validate ToJSON instance matches ToSchema for a given value and pattern checker. This can be used with QuickCheck to ensure those instances are coherent.

For validation without patterns see validateToJSON.

Using Value and Schema

validateJSON :: Definitions Schema -> Schema -> Value -> [ValidationError]

Validate JSON Value against Swagger Schema.

validateJSON mempty (toSchema (Proxy :: Proxy Int)) (toJSON (x :: Int)) == []

NOTE: validateJSON does not perform string pattern validation. See validateJSONWithPatternChecker.

validateJSONWithPatternChecker :: (Pattern -> Text -> Bool) -> Definitions Schema -> Schema -> Value -> [ValidationError]

Validate JSON Value agains Swagger ToSchema for a given value and pattern checker.

For validation without patterns see validateJSON.