swagger2-2.1.4.1: Swagger 2.0 data model

Maintainer | Nickolay Kudasov <nickolay@getshoptv.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Data.Swagger.Schema.Validation

Contents

- How to use validation
  - Examples
  - Validating ``Maybe``
- JSON validation

Description

Validate JSON values with Swagger Schema.

Synopsis

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

# 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

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``.

type ValidationError = String #

Validation error message.