Safe Haskell	None
Language	Haskell2010

Data.Avro.Schema

Contents

Schema description types
Lower level utilities

Description

Avro Schemas, represented here as values of type Schema, describe the serialization and de-serialization of values.

In Avro schemas are compose-able such that encoding data under a schema and decoding with a variant, such as newer or older version of the original schema, can be accomplished by using the Deconflict module.

Synopsis

type Schema = Type
data Type
- = Null
- | Boolean
- | Int
- | Long
- | Float
- | Double
- | Bytes
- | String
- | Array {
  - item :: Type
  }
- | Map {
  - values :: Type
  }
- | NamedType TypeName
- | Record {
  - name :: TypeName
  - namespace :: Maybe Text
  - aliases :: [TypeName]
  - doc :: Maybe Text
  - order :: Maybe Order
  - fields :: [Field]
  }
- | Enum {
  - name :: TypeName
  - namespace :: Maybe Text
  - aliases :: [TypeName]
  - doc :: Maybe Text
  - symbols :: [Text]
  - symbolLookup :: Int64 -> Maybe Text
  }
- | Union {
  - options :: NonEmpty Type
  - unionLookup :: Int64 -> Maybe Type
  }
- | Fixed {
  - name :: TypeName
  - namespace :: Maybe Text
  - aliases :: [TypeName]
  - size :: Int
  }
data Field = Field {
- fldName :: Text
- fldAliases :: [Text]
- fldDoc :: Maybe Text
- fldOrder :: Maybe Order
- fldType :: Type
- fldDefault :: Maybe (Value Type)
}
data Order
- = Ascending
- | Descending
- | Ignore
newtype TypeName = TN {
- unTN :: Text
}
mkEnum :: TypeName -> [TypeName] -> Maybe Text -> Maybe Text -> [Text] -> Type
mkUnion :: NonEmpty Type -> Type
validateSchema :: Schema -> Parser ()
typeName :: Type -> Text
buildTypeEnvironment :: Applicative m => (TypeName -> m Type) -> Type -> TypeName -> m Type
data Result a
- = Success a
- | Error String
resultToEither :: Result b -> Either String b
matches :: Type -> Type -> Bool
parseBytes :: Text -> Result ByteString
serializeBytes :: ByteString -> Text
parseAvroJSON :: (Type -> Value -> Result (Value Type)) -> (Text -> Maybe Type) -> Type -> Value -> Result (Value Type)

Schema description types

type Schema = Type Source #

An Avro schema is either * A "JSON object in the form `{"type":"typeName" ...` * A "JSON string, naming a defined type" (basic type wo free variablesnames) * A "JSON array, representing a union"

N.B. It is possible to create a Haskell value (of Schema type) that is not a valid Avro schema by violating one of the above or one of the conditions called out in validateSchema.

data Type Source #

Avro types are considered either primitive (string, int, etc) or complex/declared (structures, unions etc).

Constructors

Null
Boolean
Int
Long
Float
Double
Bytes
String
Array
Fields item :: Type
Map
Fields values :: Type
NamedType TypeName
Record
Fields name :: TypeName namespace :: Maybe Text aliases :: [TypeName] doc :: Maybe Text order :: Maybe Order fields :: [Field]
Enum
Fields name :: TypeName namespace :: Maybe Text aliases :: [TypeName] doc :: Maybe Text symbols :: [Text] symbolLookup :: Int64 -> Maybe Text
Union
Fields options :: NonEmpty Type unionLookup :: Int64 -> Maybe Type
Fixed
Fields name :: TypeName namespace :: Maybe Text aliases :: [TypeName] size :: Int

Instances

Eq Type Source #
Instance details Defined in Data.Avro.Schema Methods (==) :: Type -> Type -> Bool # (/=) :: Type -> Type -> Bool #
Show Type Source #
Instance details Defined in Data.Avro.Schema Methods showsPrec :: Int -> Type -> ShowS # show :: Type -> String # showList :: [Type] -> ShowS #
ToJSON Type Source #
Instance details Defined in Data.Avro.Schema Methods toJSON :: Type -> Value # toEncoding :: Type -> Encoding # toJSONList :: [Type] -> Value # toEncodingList :: [Type] -> Encoding #
FromJSON Type Source #
Instance details Defined in Data.Avro.Schema Methods parseJSON :: Value -> Parser Type # parseJSONList :: Value -> Parser [Type] #
ToJSON (Value Type) Source #
Instance details Defined in Data.Avro.Schema Methods toJSON :: Value Type -> Value0 # toEncoding :: Value Type -> Encoding # toJSONList :: [Value Type] -> Value0 # toEncodingList :: [Value Type] -> Encoding #
EncodeAvro (Value Type) Source #
Instance details Defined in Data.Avro.Encode Methods avro :: Value Type -> AvroM Source #

data Field Source #

Constructors

Field
Fields fldName :: Text fldAliases :: [Text] fldDoc :: Maybe Text fldOrder :: Maybe Order fldType :: Type fldDefault :: Maybe (Value Type)

Instances

Eq Field Source #
Instance details Defined in Data.Avro.Schema Methods (==) :: Field -> Field -> Bool # (/=) :: Field -> Field -> Bool #
Show Field Source #
Instance details Defined in Data.Avro.Schema Methods showsPrec :: Int -> Field -> ShowS # show :: Field -> String # showList :: [Field] -> ShowS #
ToJSON Field Source #
Instance details Defined in Data.Avro.Schema Methods toJSON :: Field -> Value # toEncoding :: Field -> Encoding # toJSONList :: [Field] -> Value # toEncodingList :: [Field] -> Encoding #
FromJSON Field Source #
Instance details Defined in Data.Avro.Schema Methods parseJSON :: Value -> Parser Field # parseJSONList :: Value -> Parser [Field] #

data Order Source #

Constructors

Ascending
Descending
Ignore

Instances

Eq Order Source #
Instance details Defined in Data.Avro.Schema Methods (==) :: Order -> Order -> Bool # (/=) :: Order -> Order -> Bool #
Ord Order Source #
Instance details Defined in Data.Avro.Schema Methods compare :: Order -> Order -> Ordering # (<) :: Order -> Order -> Bool # (<=) :: Order -> Order -> Bool # (>) :: Order -> Order -> Bool # (>=) :: Order -> Order -> Bool # max :: Order -> Order -> Order # min :: Order -> Order -> Order #
Show Order Source #
Instance details Defined in Data.Avro.Schema Methods showsPrec :: Int -> Order -> ShowS # show :: Order -> String # showList :: [Order] -> ShowS #
ToJSON Order Source #
Instance details Defined in Data.Avro.Schema Methods toJSON :: Order -> Value # toEncoding :: Order -> Encoding # toJSONList :: [Order] -> Value # toEncodingList :: [Order] -> Encoding #
FromJSON Order Source #
Instance details Defined in Data.Avro.Schema Methods parseJSON :: Value -> Parser Order # parseJSONList :: Value -> Parser [Order] #

newtype TypeName Source #

Constructors

TN
Fields unTN :: Text

Instances

Eq TypeName Source #
Instance details Defined in Data.Avro.Schema Methods (==) :: TypeName -> TypeName -> Bool # (/=) :: TypeName -> TypeName -> Bool #
Ord TypeName Source #
Instance details Defined in Data.Avro.Schema Methods compare :: TypeName -> TypeName -> Ordering # (<) :: TypeName -> TypeName -> Bool # (<=) :: TypeName -> TypeName -> Bool # (>) :: TypeName -> TypeName -> Bool # (>=) :: TypeName -> TypeName -> Bool # max :: TypeName -> TypeName -> TypeName # min :: TypeName -> TypeName -> TypeName #
Show TypeName Source #
Instance details Defined in Data.Avro.Schema Methods showsPrec :: Int -> TypeName -> ShowS # show :: TypeName -> String # showList :: [TypeName] -> ShowS #
IsString TypeName Source #
Instance details Defined in Data.Avro.Schema Methods fromString :: String -> TypeName #
Semigroup TypeName Source #
Instance details Defined in Data.Avro.Schema Methods (<>) :: TypeName -> TypeName -> TypeName # sconcat :: NonEmpty TypeName -> TypeName # stimes :: Integral b => b -> TypeName -> TypeName #
Monoid TypeName Source #
Instance details Defined in Data.Avro.Schema Methods mempty :: TypeName # mappend :: TypeName -> TypeName -> TypeName # mconcat :: [TypeName] -> TypeName #
Hashable TypeName Source #
Instance details Defined in Data.Avro.Schema Methods hashWithSalt :: Int -> TypeName -> Int # hash :: TypeName -> Int #
ToJSON TypeName Source #
Instance details Defined in Data.Avro.Schema Methods toJSON :: TypeName -> Value # toEncoding :: TypeName -> Encoding # toJSONList :: [TypeName] -> Value # toEncodingList :: [TypeName] -> Encoding #
FromJSON TypeName Source #
Instance details Defined in Data.Avro.Schema Methods parseJSON :: Value -> Parser TypeName # parseJSONList :: Value -> Parser [TypeName] #

mkEnum :: TypeName -> [TypeName] -> Maybe Text -> Maybe Text -> [Text] -> Type Source #

mkEnum name aliases namespace docs syms Constructs an Enum schema using the enumeration type's name, aliases (if any), namespace, documentation, and list of symbols that inhabit the enumeration.

mkUnion :: NonEmpty Type -> Type Source #

mkUnion subTypes Defines a union of the provided subTypes. N.B. it is invalid Avro to include another union or to have more than one of the same type as a direct member of the union. No check is done for this condition!

validateSchema :: Schema -> Parser () Source #

Placeholder NO-OP function!

Validates a schema to ensure:

All types are defined
Unions do not directly contain other unions
Unions are not ambiguous (may not contain more than one schema with the same type except for named types of record, fixed and enum)
Default values for unions can be cast as the type indicated by the first structure.
Default values can be cast/de-serialize correctly.
Named types are resolvable

Lower level utilities

typeName :: Type -> Text Source #

Get the name of the type. In the case of unions, get the name of the first value in the union schema.

buildTypeEnvironment :: Applicative m => (TypeName -> m Type) -> Type -> TypeName -> m Type Source #

buildTypeEnvironment schema builds a function mapping type names to the types declared in the traversed schema. Notice this function does not currently handle namespaces in a correct manner, possibly allowing for bad environment lookups when used on complex schemas.

data Result a Source #

Constructors

Success a
Error String

Instances

Monad Result Source #
Instance details Defined in Data.Avro.Schema Methods (>>=) :: Result a -> (a -> Result b) -> Result b # (>>) :: Result a -> Result b -> Result b # return :: a -> Result a # fail :: String -> Result a #
Functor Result Source #
Instance details Defined in Data.Avro.Schema Methods fmap :: (a -> b) -> Result a -> Result b # (<$) :: a -> Result b -> Result a #
MonadFail Result Source #
Instance details Defined in Data.Avro.Schema Methods fail :: String -> Result a #
Applicative Result Source #
Instance details Defined in Data.Avro.Schema Methods pure :: a -> Result a # (<>) :: Result (a -> b) -> Result a -> Result b # liftA2 :: (a -> b -> c) -> Result a -> Result b -> Result c # (>) :: Result a -> Result b -> Result b # (<*) :: Result a -> Result b -> Result a #
Foldable Result Source #
Instance details Defined in Data.Avro.Schema Methods fold :: Monoid m => Result m -> m # foldMap :: Monoid m => (a -> m) -> Result a -> m # foldr :: (a -> b -> b) -> b -> Result a -> b # foldr' :: (a -> b -> b) -> b -> Result a -> b # foldl :: (b -> a -> b) -> b -> Result a -> b # foldl' :: (b -> a -> b) -> b -> Result a -> b # foldr1 :: (a -> a -> a) -> Result a -> a # foldl1 :: (a -> a -> a) -> Result a -> a # toList :: Result a -> [a] # null :: Result a -> Bool # length :: Result a -> Int # elem :: Eq a => a -> Result a -> Bool # maximum :: Ord a => Result a -> a # minimum :: Ord a => Result a -> a # sum :: Num a => Result a -> a # product :: Num a => Result a -> a #
Traversable Result Source #
Instance details Defined in Data.Avro.Schema Methods traverse :: Applicative f => (a -> f b) -> Result a -> f (Result b) # sequenceA :: Applicative f => Result (f a) -> f (Result a) # mapM :: Monad m => (a -> m b) -> Result a -> m (Result b) # sequence :: Monad m => Result (m a) -> m (Result a) #
Alternative Result Source #
Instance details Defined in Data.Avro.Schema Methods empty :: Result a # (<\|>) :: Result a -> Result a -> Result a # some :: Result a -> Result [a] # many :: Result a -> Result [a] #
MonadPlus Result Source #
Instance details Defined in Data.Avro.Schema Methods mzero :: Result a # mplus :: Result a -> Result a -> Result a #
MonadError String Result Source #
Instance details Defined in Data.Avro.Schema Methods throwError :: String -> Result a # catchError :: Result a -> (String -> Result a) -> Result a #
Eq a => Eq (Result a) Source #
Instance details Defined in Data.Avro.Schema Methods (==) :: Result a -> Result a -> Bool # (/=) :: Result a -> Result a -> Bool #
Ord a => Ord (Result a) Source #
Instance details Defined in Data.Avro.Schema Methods compare :: Result a -> Result a -> Ordering # (<) :: Result a -> Result a -> Bool # (<=) :: Result a -> Result a -> Bool # (>) :: Result a -> Result a -> Bool # (>=) :: Result a -> Result a -> Bool # max :: Result a -> Result a -> Result a # min :: Result a -> Result a -> Result a #
Show a => Show (Result a) Source #
Instance details Defined in Data.Avro.Schema Methods showsPrec :: Int -> Result a -> ShowS # show :: Result a -> String # showList :: [Result a] -> ShowS #
Semigroup (Result a) Source #
Instance details Defined in Data.Avro.Schema Methods (<>) :: Result a -> Result a -> Result a # sconcat :: NonEmpty (Result a) -> Result a # stimes :: Integral b => b -> Result a -> Result a #
Monoid (Result a) Source #
Instance details Defined in Data.Avro.Schema Methods mempty :: Result a # mappend :: Result a -> Result a -> Result a # mconcat :: [Result a] -> Result a #

resultToEither :: Result b -> Either String b Source #

matches :: Type -> Type -> Bool Source #

Checks that two schemas match. This is like equality of schemas, except NamedTypes match against other types with the same name.

This extends recursively: two records match if they have the same name, the same number of fields and the fields all match.

parseBytes :: Text -> Result ByteString Source #

Parses a string literal into a bytestring in the format expected for bytes and fixed values. Will fail if every character does not have a codepoint between 0 and 255.

serializeBytes :: ByteString -> Text Source #

Turn a ByteString into a Text that matches the format Avro expects from bytes and fixed literals in JSON. Each byte is mapped to a single Unicode codepoint between 0 and 255.

parseAvroJSON Source #

Arguments

:: (Type -> Value -> Result (Value Type))	How to handle unions. The way unions are formatted in JSON depends on whether we're parsing a normal Avro object or we're parsing a default declaration in a schema. This function will only ever be passed `Union` schemas. It should error out if this is not the case—it represents a bug in this code.
-> (Text -> Maybe Type)
-> Type
-> Value
-> Result (Value Type)

Parse JSON-encoded avro data.