Moduleswagger2-2.8.9Haskell2010

Data.Swagger.Schema.Validation

Validate JSON values with Swagger Schema.

1 type
6 values

Packageswagger2-2.8.9
Exports7
LanguageHaskell2010
LicenceBSD-3-Clause
SourceValidation.hs

How to use validation

0 declarations

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

Example1 expression

>>> validateToJSON "hello"[]

Example1 expression

>>> validateToJSON False[]

Example5 expressions

>>> 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:

Example3 expressions

>>> validateToJSON (Nothing :: Maybe String)["expected JSON value of type SwaggerString\n  with context:\n    SwaggerType: Just SwaggerString\n    Aeson Value: Null\n    Schema title: Nothing\n"]>>> validateToJSON ([Just "hello", Nothing] :: [Maybe String])["expected JSON value of type SwaggerString\n  with context:\n    SwaggerType: Just SwaggerString\n    Aeson Value: Null\n    Schema title: Nothing\n"]>>> validateToJSON (123, Nothing :: Maybe String)["expected JSON value of type SwaggerString\n  with context:\n    SwaggerType: Just SwaggerString\n    Aeson Value: Null\n    Schema title: Nothing\n"]

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

Example5 expressions

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

1 declaration

typetype ValidationError = String

Validation error message.

Using `ToJSON` and `ToSchema`

valuevalidatePrettyToJSON :: (ToJSON a, ToSchema a) => a -> Maybe String

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

Property

prop> validateToJSON (x :: Int) == []

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

See renderValidationErrors on how the output is structured.

valuevalidateToJSON :: (ToJSON a, ToSchema a) => a -> [ValidationError]

Variant of validatePrettyToJSON with typed output.

valuevalidateToJSONWithPatternChecker

:: (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. See also: renderValidationErrors.

valuerenderValidationErrors

:: (ToJSON a, ToSchema a)
=> a -> [ValidationError]
-> a
-> Maybe String

Pretty print validation errors together with actual JSON and Swagger Schema (using encodePretty).

Example10 expressions

>>> import Data.Aeson as Aeson>>> import Data.Foldable (traverse_)>>> import GHC.Generics>>> data Phone = Phone { value :: String } deriving (Generic)>>> data Person = Person { name :: String, phone :: Phone } deriving (Generic)>>> instance ToJSON Person where toJSON p = object [ "name" Aeson..= name p ]>>> instance ToSchema Phone>>> instance ToSchema Person>>> let person = Person { name = "John", phone = Phone "123456" }>>> traverse_ putStrLn $ renderValidationErrors validateToJSON personValidation against the schema fails:  * property "phone" is required, but not found in "{\"name\":\"John\"}"JSON value:{    "name": "John"}Swagger Schema:{    "properties": {        "name": {            "type": "string"        },        "phone": {            "$ref": "#/definitions/Phone"        }    },    "required": [        "name",        "phone"    ],    "type": "object"}Swagger Description Context:{    "Phone": {        "properties": {            "value": {                "type": "string"            }        },        "required": [            "value"        ],        "type": "object"    }}

Using `Value` and `Schema`

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

Validate JSON Value against Swagger Schema.

Property

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

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

valuevalidateJSONWithPatternChecker

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