| Copyright | (C) Juspay Technologies Pvt Ltd 2020 |
|---|---|
| License | MIT |
| Maintainer | koz.ross@retro-freedom.nz |
| Stability | Experimental |
| Portability | GHC only |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
Data.Medea
Contents
Description
This module contains the reference Haskell implementation of a Medea validator, providing both schema graph file loading and validation, with some convenience functions.
A minimal example of use follows. This example first attempts to load a Medea
schema graph file from /path/to/schema.medea, and, if successful, attempts
to validate the JSON file at /path/to/my.json against the schemata so
loaded.
import Data.Medea (loadSchemaFromFile, validateFromFile)
main :: IO ()
main = do
-- try to load the schema graph file
loaded <- loadSchemaFromFile "/path/to/schema.medea"
case loaded of
Left err -> print err -- or some other handling
Right scm -> do
-- try to validate
validated <- validateFromFile scm "/path/to/my.json"
case validated of
Left err -> print err -- or some other handling
Right validJson -> print validJson -- or some other useful thingFor more details about how to create Medea schema graph files, see
TUTORIAL.md and SPEC.md.
Synopsis
- data Schema
- data LoaderError
- = NotUtf8
- | ParsingFailed !(ParseErrorBundle Text ParseError)
- | StartSchemaMissing
- | SelfTypingSchema
- | MultipleSchemaDefinition !Text
- | MissingSchemaDefinition !Text !Text
- | SchemaNameReserved !Text
- | IsolatedSchemata !Text
- | MissingPropSchemaDefinition !Text !Text
- | MinimumLengthGreaterThanMaximum !Text
- | MultiplePropSchemaDefinition !Text !Text
- | MissingListSchemaDefinition !Text !Text
- | MissingTupleSchemaDefinition !Text !Text
- | PropertySpecWithoutObjectType !Text
- | ListSpecWithoutArrayType !Text
- | TupleSpecWithoutArrayType !Text
- | StringSpecWithoutStringType !Text
- data ParseError
- buildSchema :: ByteString -> Either LoaderError Schema
- loadSchemaFromFile :: MonadIO m => FilePath -> m (Either LoaderError Schema)
- loadSchemaFromHandle :: MonadIO m => Handle -> m (Either LoaderError Schema)
- data JSONType
- data SchemaInformation
- data ValidationError
- = EmptyError
- | NotJSON
- | WrongType !Value !JSONType
- | NotOneOfOptions !Value
- | AdditionalPropFoundButBanned !Text !Text
- | RequiredPropertyIsMissing !Text !Text
- | OutOfBoundsArrayLength !Text !Value
- | ImplementationError !Text
- data ValidatedJSON
- toValue :: ValidatedJSON -> Value
- validAgainst :: ValidatedJSON -> SchemaInformation
- validate :: Schema -> ByteString -> Either ValidationError ValidatedJSON
- validateFromFile :: MonadIO m => Schema -> FilePath -> m (Either ValidationError ValidatedJSON)
- validateFromHandle :: MonadIO m => Schema -> Handle -> m (Either ValidationError ValidatedJSON)
Schema loading
A compiled Medea schema.
data LoaderError Source #
Possible errors from loading Medea schemata.
Constructors
| NotUtf8 | The data provided wasn't UTF-8. |
| ParsingFailed !(ParseErrorBundle Text ParseError) | Parsing failed. |
| StartSchemaMissing | No schema labelled |
| SelfTypingSchema | A schema was typed in terms of itself. |
| MultipleSchemaDefinition !Text | A schema was defined more than once. |
| MissingSchemaDefinition | We expected a schema, but couldn't find it. |
| SchemaNameReserved !Text | A schema was named with a reserved identifier (other than |
| IsolatedSchemata !Text | An isolated schema was found. |
| MissingPropSchemaDefinition | A property schema refers to a non-existent schema. |
| MinimumLengthGreaterThanMaximum !Text | A minimum length specification was more than its corresponding maximum length specification. |
| MultiplePropSchemaDefinition | A property was specified more than once. |
| MissingListSchemaDefinition | A list specification did not provide an element type. |
| MissingTupleSchemaDefinition | A tuple specification does not provide a positional schema. |
| PropertySpecWithoutObjectType !Text | Schema had a property specification, but no |
| ListSpecWithoutArrayType !Text | Schema had a list specification, but no |
| TupleSpecWithoutArrayType !Text | Schema had a tuple specification, but no |
| StringSpecWithoutStringType !Text | Schema had a string specification, but no |
Instances
| Eq LoaderError Source # | |
Defined in Data.Medea.Loader | |
| Show LoaderError Source # | |
Defined in Data.Medea.Loader Methods showsPrec :: Int -> LoaderError -> ShowS # show :: LoaderError -> String # showList :: [LoaderError] -> ShowS # | |
data ParseError Source #
All possible errors from the Medea parser.
Constructors
| IdentifierTooLong !Text | An identifier exceeded 32 bytes. |
| ExpectedReservedIdentifier !Text | We saw a non-reserved identifier where we wanted a reserved one. |
| LeadingZero !Text | A Medea natural number had literal zeroes. |
| ConflictingSpecRequirements | We were given incompatible requirements within a specification. |
| EmptyLengthArraySpec | We were not given a length in an array specification. |
| EmptyArrayElements | We were not given an element specification in an array specification. |
| EmptyStringValuesSpec | We were given no string values in a string specification. |
Instances
| Eq ParseError Source # | |
Defined in Data.Medea.Parser.Types | |
| Ord ParseError Source # | |
Defined in Data.Medea.Parser.Types Methods compare :: ParseError -> ParseError -> Ordering # (<) :: ParseError -> ParseError -> Bool # (<=) :: ParseError -> ParseError -> Bool # (>) :: ParseError -> ParseError -> Bool # (>=) :: ParseError -> ParseError -> Bool # max :: ParseError -> ParseError -> ParseError # min :: ParseError -> ParseError -> ParseError # | |
| Show ParseError Source # | |
Defined in Data.Medea.Parser.Types Methods showsPrec :: Int -> ParseError -> ShowS # show :: ParseError -> String # showList :: [ParseError] -> ShowS # | |
| ShowErrorComponent ParseError Source # | |
Defined in Data.Medea.Parser.Types | |
buildSchema :: ByteString -> Either LoaderError Schema Source #
Attempt to produce a schema from UTF-8 data in memory.
loadSchemaFromFile :: MonadIO m => FilePath -> m (Either LoaderError Schema) Source #
Parse and process a Medea schema graph file.
Any file handle(s) will be closed if an exception is thrown.
loadSchemaFromHandle :: MonadIO m => Handle -> m (Either LoaderError Schema) Source #
Load data corresponding to a Medea schema graph file from a Handle.
This relies on hGetContents to do its work, and all caveats about the state
a Handle can be left in afterwards apply here.
Schema validation
The basic types of JSON value (as per ECMA-404).
Constructors
| JSONNull | |
| JSONBoolean | |
| JSONNumber | |
| JSONString | |
| JSONArray | |
| JSONObject |
Instances
| Eq JSONType Source # | |
| Ord JSONType Source # | |
Defined in Data.Medea.JSONType | |
| Show JSONType Source # | |
| Generic JSONType Source # | |
| Hashable JSONType Source # | |
Defined in Data.Medea.JSONType | |
| type Rep JSONType Source # | |
Defined in Data.Medea.JSONType type Rep JSONType = D1 (MetaData "JSONType" "Data.Medea.JSONType" "medea-1.2.0-inplace" False) ((C1 (MetaCons "JSONNull" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "JSONBoolean" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "JSONNumber" PrefixI False) (U1 :: Type -> Type))) :+: (C1 (MetaCons "JSONString" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "JSONArray" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "JSONObject" PrefixI False) (U1 :: Type -> Type)))) | |
data SchemaInformation Source #
An annotation, describing which schema a given chunk of JSON was deemed to be valid against.
Constructors
| AnySchema | No requirements were placed on this chunk. |
| NullSchema | Validated as JSON |
| BooleanSchema | Validated as JSON boolean. |
| NumberSchema | Validated as JSON number. |
| StringSchema | Validated as JSON string. |
| ArraySchema | Validated as JSON array. |
| ObjectSchema | Validated as JSON object. |
| StartSchema | Validated against the start schema. |
| UserDefined !Text | Validated against the schema with the given name. |
Instances
data ValidationError Source #
All possible validation errors.
Constructors
| EmptyError | |
| NotJSON | We could not parse JSON out of what we were provided. |
| WrongType | We got a type different to what we expected. |
Fields
| |
| NotOneOfOptions !Value | We expected one of several possibilities, but got something that fits none. |
| AdditionalPropFoundButBanned | We found a JSON object with a property that wasn't specified in its schema, and additional properties are forbidden. |
| RequiredPropertyIsMissing | We found a JSON object which is missing a property its schema requires. |
| OutOfBoundsArrayLength | We found a JSON array which falls outside of the minimum or maximum length constraints its corresponding schema demands. |
Fields
| |
| ImplementationError !Text | This is a bug - please report it to us! |
Instances
data ValidatedJSON Source #
JSON, annotated with what schemata it was deemed valid against.
Instances
| Eq ValidatedJSON Source # | |
Defined in Data.Medea Methods (==) :: ValidatedJSON -> ValidatedJSON -> Bool # (/=) :: ValidatedJSON -> ValidatedJSON -> Bool # | |
| Data ValidatedJSON Source # | |
Defined in Data.Medea Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> ValidatedJSON -> c ValidatedJSON # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c ValidatedJSON # toConstr :: ValidatedJSON -> Constr # dataTypeOf :: ValidatedJSON -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c ValidatedJSON) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c ValidatedJSON) # gmapT :: (forall b. Data b => b -> b) -> ValidatedJSON -> ValidatedJSON # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> ValidatedJSON -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> ValidatedJSON -> r # gmapQ :: (forall d. Data d => d -> u) -> ValidatedJSON -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> ValidatedJSON -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> ValidatedJSON -> m ValidatedJSON # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> ValidatedJSON -> m ValidatedJSON # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> ValidatedJSON -> m ValidatedJSON # | |
| Show ValidatedJSON Source # | |
Defined in Data.Medea Methods showsPrec :: Int -> ValidatedJSON -> ShowS # show :: ValidatedJSON -> String # showList :: [ValidatedJSON] -> ShowS # | |
| NFData ValidatedJSON Source # | |
Defined in Data.Medea Methods rnf :: ValidatedJSON -> () # | |
| Hashable ValidatedJSON Source # | |
Defined in Data.Medea | |
toValue :: ValidatedJSON -> Value Source #
Convert to an Aeson Value, throwing away all schema information.
validAgainst :: ValidatedJSON -> SchemaInformation Source #
What schema did this validate against?
validate :: Schema -> ByteString -> Either ValidationError ValidatedJSON Source #
Attempt to construct validated JSON from a strict bytestring. This will attempt to decode using Aeson before validating.
If this fails, it will return the first failure condition; that is, the one caused by the first node in a depth-first, right-to-left, document-order traversal of the input JSON.
validateFromFile :: MonadIO m => Schema -> FilePath -> m (Either ValidationError ValidatedJSON) Source #
Helper for construction of validated JSON from a JSON file.
This will attempt to decode using Aeson before validating. This will return
errors on failure in the same way as validate does.
This will clean up any file handle(s) if any exceptions are thrown.
validateFromHandle :: MonadIO m => Schema -> Handle -> m (Either ValidationError ValidatedJSON) Source #