Maintainer | Nickolay Kudasov <nickolay@getshoptv.com> |
---|---|
Stability | experimental |
Safe Haskell | None |
Language | Haskell2010 |
Validate JSON values with Swagger Schema.
Synopsis
- type ValidationError = String
- validatePrettyToJSON :: forall a. (ToJSON a, ToSchema a) => a -> Maybe String
- validateToJSON :: forall a. (ToJSON a, ToSchema a) => a -> [ValidationError]
- validateToJSONWithPatternChecker :: forall a. (ToJSON a, ToSchema a) => (Pattern -> Text -> Bool) -> a -> [ValidationError]
- renderValidationErrors :: forall a. (ToJSON a, ToSchema a) => (a -> [ValidationError]) -> a -> Maybe String
- validateJSON :: Definitions Schema -> Schema -> Value -> [ValidationError]
- validateJSONWithPatternChecker :: (Pattern -> Text -> Bool) -> Definitions Schema -> Schema -> Value -> [ValidationError]
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
Maybe
Because
has the same schema as Maybe
aa
, validation
generally fails for null
JSON:
>>>
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
is a type of a record field,
validation takes Maybe
a
property of the required
into account:Schema
>>>
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 Source #
Validation error message.
Using ToJSON
and ToSchema
validatePrettyToJSON :: forall a. (ToJSON a, ToSchema a) => a -> Maybe String Source #
Validate
instance matches ToJSON
for a given value.
This can be used with QuickCheck to ensure those instances are coherent:ToSchema
validateToJSON (x :: Int) == []
NOTE:
does not perform string pattern validation.
See validateToJSON
.validateToJSONWithPatternChecker
See renderValidationErrors
on how the output is structured.
validateToJSON :: forall a. (ToJSON a, ToSchema a) => a -> [ValidationError] Source #
Variant of validatePrettyToJSON
with typed output.
validateToJSONWithPatternChecker :: forall a. (ToJSON a, ToSchema a) => (Pattern -> Text -> Bool) -> a -> [ValidationError] Source #
Validate
instance matches ToJSON
for a given value and pattern checker.
This can be used with QuickCheck to ensure those instances are coherent.ToSchema
For validation without patterns see
. See also:
validateToJSON
renderValidationErrors
.
renderValidationErrors :: forall a. (ToJSON a, ToSchema a) => (a -> [ValidationError]) -> a -> Maybe String Source #
Pretty print validation errors
together with actual JSON and Swagger Schema
(using encodePretty
).
>>>
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 person
Validation 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
validateJSON :: Definitions Schema -> Schema -> Value -> [ValidationError] Source #
Validate JSON
against Swagger Value
.Schema
validateJSON mempty (toSchema (Proxy :: Proxy Int)) (toJSON (x :: Int)) == []
NOTE:
does not perform string pattern validation.
See validateJSON
.validateJSONWithPatternChecker
validateJSONWithPatternChecker :: (Pattern -> Text -> Bool) -> Definitions Schema -> Schema -> Value -> [ValidationError] Source #
Validate JSON
agains Swagger Value
for a given value and pattern checker.ToSchema
For validation without patterns see
.validateJSON