aeson-schemas-1.0.2: Easily consume JSON data on-demand with type-safety

MaintainerBrandon Chinn <brandon@leapyear.io>
Stabilityexperimental
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Data.Aeson.Schema.TH

Contents

Description

Template Haskell definitions for doing various aeson-schemas operations.

SchemaType defines the shape of the JSON object stored in Object, and we can use getKey to lookup a key that is checked at compile-time to exist in the object.

To make it easier to extract deeply nested keys, this module defines QuasiQuoters that generate the corresponding getKey expressions.

In addition to the QuasiQuotes extension, the following extensions will need to be enabled to use these QuasiQuoters:

  • DataKinds
  • FlexibleContexts
  • TypeFamilies
Synopsis

Documentation

schema :: QuasiQuoter Source #

Defines a QuasiQuoter for writing schemas.

Example:

import Data.Aeson.Schema (schema)

type MySchema = [schema|
  {
    foo: {
      a: Int,
      // you can add comments like this
      nodes: List {
        b: Maybe Bool,
      },
      c: Text,
      d: Text,
      e: MyType,
      f: Maybe List {
        name: Text,
      },
    },
  }
|]

Syntax:

  • { key: <schema>, ... } corresponds to a JSON Object with the given key mapping to the given schema.
  • Bool, Int, Double, and Text correspond to the usual Haskell values.
  • Maybe <schema> and List <schema> correspond to Maybe and [], containing values specified by the provided schema (no parentheses needed).
  • Any other uppercase identifier corresponds to the respective type in scope -- requires a FromJSON instance.
  • { key: #Other, ... } maps the given key to the Other schema.
  • { #Other, ... } extends this schema with the Other schema.

get :: QuasiQuoter Source #

Defines a QuasiQuoter for extracting JSON data.

Example:

let Just result = decode ... :: Maybe (Object MySchema)

[get| result.foo.a |]          :: Int
[get| result.foo.nodes |]      :: [Object (..)]
[get| result.foo.nodes[] |]    :: [Object (..)]
[get| result.foo.nodes[].b |]  :: [Maybe Bool]
[get| result.foo.nodes[].b! |] :: [Bool] -- runtime error if any values are Nothing
[get| result.foo.c |]          :: Text
[get| result.foo.(a,c) |]      :: (Int, Text)
[get| result.foo.[c,d] |]      :: [Text]

let nodes = [get| result.foo.nodes |]
flip map nodes $ \node -> fromMaybe ([get| node.num |] == 0) [get| node.b |]
map [get| .num |] nodes

Syntax:

  • x.y is only valid if x is an Object. Returns the value of the key y.
  • .y returns a function that takes in an Object and returns the value of the key y.
  • x.[y,z.a] is only valid if x is an Object, and if y and z.a have the same type. Returns the value of the operations y and z.a as a list. MUST be the last operation.
  • x.(y,z.a) is only valid if x is an Object. Returns the value of the operations y and z.a as a tuple. MUST be the last operation.
  • x! is only valid if x is a Maybe. Unwraps the value of x from a Just value and errors (at runtime!) if x is Nothing.
  • x[] is only valid if x is a list. Applies the remaining rules as an fmap over the values in the list, e.g.

    • x[] without anything after is equivalent to x
    • x[].y gets the key y in all the Objects in x
    • x[]! unwraps all Just values in x (and errors if any Nothing values exist in x)
  • x? follows the same rules as x[] except it's only valid if x is a Maybe.

unwrap :: QuasiQuoter Source #

Defines a QuasiQuoter to extract a schema within the given schema.

For example:

-- | MyFoo ~ Object [schema| { b: Maybe Bool } |]
type MyFoo = [unwrap| MySchema.foo.nodes[] |]

If the schema is imported qualified, you can use parentheses to distinguish it from the expression:

type MyFoo = [unwrap| (MyModule.Schema).foo.nodes[] |]

You can then use the type alias as usual:

parseBar :: MyFoo -> String
parseBar = maybe "null" show . [get| .b |]

foo = map parseBar [get| result.foo.nodes[] |]

The syntax is mostly the same as get, except the operations run on the type itself, instead of the values. Differences from get:

  • x! is only valid if x is a Maybe a type. Returns a, the type wrapped in the Maybe.
  • x? is the same as x!.
  • x[] is only valid if x is a [a] type. Returns a, the type contained in the list.

Utilities

mkGetter :: String -> String -> Name -> String -> DecsQ Source #

A helper that generates a get expression and a type alias for the result of the expression.

mkGetter "Node" "getNodes" ''MySchema ".nodes![]"

-- is equivalent to:
type Node = [unwrap| MySchema.nodes[] |] -- Object [schema| { b: Maybe Bool } |]
getNodes :: Object MySchema -> [Node]
getNodes = [get| .nodes![] |]

mkGetter takes four arguments:

unwrapName
The name of the type synonym to store the unwrapped schema as
funcName
The name of the getter function
startSchema
The schema to extract/unwrap from
ops
The operation to pass to the get and unwrap quasiquoters

There is one subtlety that occurs from the use of the same ops string for both the unwrap and get quasiquoters: unwrap strips out intermediate functors, while get applies within the functor. So in the above example, ".nodes![]" strips out the list when saving the schema to Node, while in the below example, ".nodes!" doesn't strip out the list when saving the schema to Nodes.

mkGetter "Nodes" "getNodes" ''MySchema ".nodes"

-- is equivalent to:
type Nodes = [unwrap| MySchema.nodes! |] -- [Object [schema| { b: Maybe Bool } |]]
getNodes :: Object MySchema -> Nodes
getNodes = [get| .nodes! |]

As another example,

mkGetter "MyName" "getMyName" ''MySchema ".f?[].name"

-- is equivalent to:
type MyName = [unwrap| MySchema.f?[].name |] -- Text
getMyBool :: Object MySchema -> Maybe [MyName]
getMyBool = [get| .f?[].name |]

Helpers for Enum types

mkEnum :: String -> [String] -> Q [Dec] Source #

Make an enum type with the given constructors, that can be parsed from JSON.

The FromJSON instance will match to a string value matching the constructor name, case-insensitive.

mkEnum State [OPEN, CLOSED]

main = print
  [ decode "open" :: Maybe State
  , decode "OPEN" :: Maybe State
  , decode "closed" :: Maybe State
  , decode "CLOSED" :: Maybe State
  ]

genFromJSONEnum :: Name -> Q [Dec] Source #

Generate an instance of FromJSON for the given data type.

Prefer using mkEnum; this function is useful for data types in which you want greater control over the actual data type.

The FromJSON instance will match to a string value matching the constructor name, case-insensitive.

data State = OPEN | CLOSED deriving (Show,Enum)
genFromJSONEnum ''State

main = print
  [ decode "open" :: Maybe State
  , decode "OPEN" :: Maybe State
  , decode "closed" :: Maybe State
  , decode "CLOSED" :: Maybe State
  ]