-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A schema language for JSON.
--   
--   A reference implementation of a schema language, together with a
--   conformance suite and a specification.
@package medea
@version 1.2.0


-- | 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 <tt>/path/to/schema.medea</tt>, and, if
--   successful, attempts to validate the JSON file at
--   <tt>/path/to/my.json</tt> against the schemata so loaded.
--   
--   <pre>
--   import Data.Medea (loadSchemaFromFile, validateFromFile)
--   
--   main :: IO ()
--   main = do
--     -- try to load the schema graph file
--     loaded &lt;- loadSchemaFromFile "/path/to/schema.medea"
--     case loaded of
--        Left err -&gt; print err -- or some other handling
--        Right scm -&gt; do
--          -- try to validate
--          validated &lt;- validateFromFile scm "/path/to/my.json"
--          case validated of
--            Left err -&gt; print err -- or some other handling
--            Right validJson -&gt; print validJson -- or some other useful thing
--   </pre>
--   
--   For more details about how to create Medea schema graph files, see
--   <tt>TUTORIAL.md</tt> and <tt>SPEC.md</tt>.
module Data.Medea

-- | A compiled Medea schema.
data Schema

-- | Possible errors from loading Medea schemata.
data LoaderError

-- | The data provided wasn't UTF-8.
NotUtf8 :: LoaderError

-- | Parsing failed.
ParsingFailed :: !ParseErrorBundle Text ParseError -> LoaderError

-- | No schema labelled <tt>$start</tt> was provided.
StartSchemaMissing :: LoaderError

-- | A schema was typed in terms of itself.
SelfTypingSchema :: LoaderError

-- | A schema was defined more than once.
MultipleSchemaDefinition :: {-# UNPACK #-} !Text -> LoaderError

-- | We expected a schema, but couldn't find it.
MissingSchemaDefinition :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> LoaderError

-- | A schema was named with a reserved identifier (other than
--   <tt>start</tt>).
SchemaNameReserved :: {-# UNPACK #-} !Text -> LoaderError

-- | An isolated schema was found.
IsolatedSchemata :: {-# UNPACK #-} !Text -> LoaderError

-- | A property schema refers to a non-existent schema.
MissingPropSchemaDefinition :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> LoaderError

-- | A minimum length specification was more than its corresponding maximum
--   length specification.
MinimumLengthGreaterThanMaximum :: {-# UNPACK #-} !Text -> LoaderError

-- | A property was specified more than once.
MultiplePropSchemaDefinition :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> LoaderError

-- | A list specification did not provide an element type.
MissingListSchemaDefinition :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> LoaderError

-- | A tuple specification does not provide a positional schema.
MissingTupleSchemaDefinition :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> LoaderError

-- | Schema had a property specification, but no <tt>$object</tt> type.
PropertySpecWithoutObjectType :: {-# UNPACK #-} !Text -> LoaderError

-- | Schema had a list specification, but no <tt>$array</tt> type.
ListSpecWithoutArrayType :: {-# UNPACK #-} !Text -> LoaderError

-- | Schema had a tuple specification, but no <tt>$array</tt> type.
TupleSpecWithoutArrayType :: {-# UNPACK #-} !Text -> LoaderError

-- | Schema had a string specification, but no <tt>$string</tt> type.
StringSpecWithoutStringType :: {-# UNPACK #-} !Text -> LoaderError

-- | All possible errors from the Medea parser.
data ParseError

-- | An identifier exceeded 32 bytes.
IdentifierTooLong :: {-# UNPACK #-} !Text -> ParseError

-- | We saw a non-reserved identifier where we wanted a reserved one.
ExpectedReservedIdentifier :: {-# UNPACK #-} !Text -> ParseError

-- | A Medea natural number had literal zeroes.
LeadingZero :: {-# UNPACK #-} !Text -> ParseError

-- | We were given incompatible requirements within a specification.
ConflictingSpecRequirements :: ParseError

-- | We were not given a length in an array specification.
EmptyLengthArraySpec :: ParseError

-- | We were not given an element specification in an array specification.
EmptyArrayElements :: ParseError

-- | We were given no string values in a string specification.
EmptyStringValuesSpec :: ParseError

-- | Attempt to produce a schema from UTF-8 data in memory.
buildSchema :: ByteString -> Either LoaderError Schema

-- | Parse and process a Medea schema graph file.
--   
--   Any file handle(s) will be closed if an exception is thrown.
loadSchemaFromFile :: MonadIO m => FilePath -> m (Either LoaderError Schema)

-- | Load data corresponding to a Medea schema graph file from a
--   <a>Handle</a>.
--   
--   This relies on <a>hGetContents</a> to do its work, and all caveats
--   about the state a <a>Handle</a> can be left in afterwards apply here.
loadSchemaFromHandle :: MonadIO m => Handle -> m (Either LoaderError Schema)

-- | The basic types of JSON value (as per <a>ECMA-404</a>).
data JSONType
JSONNull :: JSONType
JSONBoolean :: JSONType
JSONNumber :: JSONType
JSONString :: JSONType
JSONArray :: JSONType
JSONObject :: JSONType

-- | An annotation, describing which schema a given chunk of JSON was
--   deemed to be valid against.
data SchemaInformation

-- | No requirements were placed on this chunk.
AnySchema :: SchemaInformation

-- | Validated as JSON <tt>null</tt>.
NullSchema :: SchemaInformation

-- | Validated as JSON boolean.
BooleanSchema :: SchemaInformation

-- | Validated as JSON number.
NumberSchema :: SchemaInformation

-- | Validated as JSON string.
StringSchema :: SchemaInformation

-- | Validated as JSON array.
ArraySchema :: SchemaInformation

-- | Validated as JSON object.
ObjectSchema :: SchemaInformation

-- | Validated against the start schema.
StartSchema :: SchemaInformation

-- | Validated against the schema with the given name.
UserDefined :: {-# UNPACK #-} !Text -> SchemaInformation

-- | All possible validation errors.
data ValidationError
EmptyError :: ValidationError

-- | We could not parse JSON out of what we were provided.
NotJSON :: ValidationError

-- | We got a type different to what we expected.
WrongType :: !Value -> !JSONType -> ValidationError

-- | We expected one of several possibilities, but got something that fits
--   none.
NotOneOfOptions :: !Value -> ValidationError

-- | We found a JSON object with a property that wasn't specified in its
--   schema, and additional properties are forbidden.
AdditionalPropFoundButBanned :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> ValidationError

-- | We found a JSON object which is missing a property its schema
--   requires.
RequiredPropertyIsMissing :: {-# UNPACK #-} !Text -> {-# UNPACK #-} !Text -> ValidationError

-- | We found a JSON array which falls outside of the minimum or maximum
--   length constraints its corresponding schema demands.
OutOfBoundsArrayLength :: {-# UNPACK #-} !Text -> !Value -> ValidationError

-- | This is a bug - please report it to us!
ImplementationError :: {-# UNPACK #-} !Text -> ValidationError

-- | JSON, annotated with what schemata it was deemed valid against.
data ValidatedJSON

-- | Convert to an Aeson <a>Value</a>, throwing away all schema
--   information.
toValue :: ValidatedJSON -> Value

-- | What schema did this validate against?
validAgainst :: ValidatedJSON -> SchemaInformation

-- | 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.
validate :: Schema -> ByteString -> Either ValidationError ValidatedJSON

-- | 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 <a>validate</a> does.
--   
--   This will clean up any file handle(s) if any exceptions are thrown.
validateFromFile :: MonadIO m => Schema -> FilePath -> m (Either ValidationError ValidatedJSON)

-- | Helper for construction of validated JSON from a <a>Handle</a>. This
--   will attempt to decode using Aeson before validating. This will return
--   errors on failure in the same way as <a>validate</a> does.
--   
--   This will close the <a>Handle</a> upon finding EOF, or if an exception
--   is thrown.
validateFromHandle :: MonadIO m => Schema -> Handle -> m (Either ValidationError ValidatedJSON)
instance Control.Monad.Error.Class.MonadError Data.Medea.ValidationError Data.Medea.ValidationM
instance Control.Monad.State.Class.MonadState (Data.Set.NonEmpty.Internal.NESet Data.Medea.Analysis.TypeNode, GHC.Maybe.Maybe Data.Medea.Parser.Primitive.Identifier) Data.Medea.ValidationM
instance Control.Monad.Reader.Class.MonadReader Data.Medea.Schema.Schema Data.Medea.ValidationM
instance GHC.Base.Monad Data.Medea.ValidationM
instance GHC.Base.Applicative Data.Medea.ValidationM
instance GHC.Base.Functor Data.Medea.ValidationM
instance Data.Hashable.Class.Hashable Data.Medea.ValidationError
instance GHC.Generics.Generic Data.Medea.ValidationError
instance GHC.Show.Show Data.Medea.ValidationError
instance GHC.Classes.Eq Data.Medea.ValidationError
instance GHC.Show.Show Data.Medea.ValidatedJSON
instance GHC.Classes.Eq Data.Medea.ValidatedJSON
instance Data.Data.Data Data.Medea.ValidatedJSON
instance Control.DeepSeq.NFData Data.Medea.SchemaInformation
instance Data.Hashable.Class.Hashable Data.Medea.SchemaInformation
instance GHC.Generics.Generic Data.Medea.SchemaInformation
instance GHC.Show.Show Data.Medea.SchemaInformation
instance Data.Data.Data Data.Medea.SchemaInformation
instance GHC.Classes.Eq Data.Medea.SchemaInformation
instance GHC.Base.Alternative Data.Medea.ValidationM
instance GHC.Base.Semigroup Data.Medea.ValidationError
instance GHC.Base.Monoid Data.Medea.ValidationError
instance Control.DeepSeq.NFData Data.Medea.ValidatedJSON
instance Data.Hashable.Class.Hashable Data.Medea.ValidatedJSON