Simple DSL for defining type level "specifications" for JSON data. Similar in spirit to (but not isomorphic with) JSON Schema.

Intended to be used at the type level using -XDataKinds

See JSONStructure for how these map into Haskell representations.

Alias for Required.

Alias for Optional.

Specify a field in an object.

Types of this class can be encoded to JSON according to a type-level Specification.

Types of this class can be JSON decoded according to a type-level Specification.

Helper for defining ToJSON and FromJSON instances based on HasEncodingJsonSpec.

Use with -XDerivingVia like:

data MyObj = MyObj
  { foo :: Int
  , bar :: Text
  }
  deriving (ToJSON, FromJSON) via (SpecJSON MyObj)
instance HasEncodingSpec MyObj where ...
instance HasDecodingSpec MyObj where ...

Structural representation of JsonTag. (I.e. a constant string value.)

Structural representation of an object field.

This is the "Haskell structure" type of JsonRef references.

The main reason why we need this is because of recursion, as explained below:

Since the specification is at the type level, and type level haskell is strict, specifying a recursive definition the "naive" way would cause an infinitely sized type.

For example this won't work:

data Foo = Foo [Foo]
instance HasJsonEncodingSpec Foo where
  type EncodingSpec Foo = JsonArray (EncodingSpec Foo)
  toJSONStructure = ... can't be written

... because EncodingSpec Foo would expand strictly into an array of EncodingSpec Foo, which would expand strictly... to infinity.

Using JsonLet prevents the specification type from being infinitely sized, but what about the "structure" type which holds real values corresponding to the spec? The structure type has to have some way to reference itself or else it too would be infinitely sized.

In order to "reference itself" the structure type has to go through a newtype somewhere along the way, and that's what this type is for. Whenever you use a JsonRef in the spec, the corresponding structural type will have a Ref newtype wrapper around the "dereferenced" structure type.

For example:

data Foo = Foo [Foo]
instance HasJsonEncodingSpec Foo where
  type EncodingSpec Foo =
    JsonLet
      '[ '("Foo", JsonArray (JsonRef "Foo")) ]
      (JsonRef "Foo")
  toJSONStructure (Foo fs) =
    Ref [ toJSONStructure <$> fs ]

Strictly speaking, we wouldn't necessarily have to translate every JsonRef into a Ref. In principal we could get away with inserting a Ref somewhere in every mutually recursive cycle. But the type level programming to figure that out a) probably wouldn't do any favors to compilation times, b) is beyond what I'm willing to attempted right now, and c) requires some kind of deterministic and stable choice about where to insert the Ref (which I'm not even certain exists) lest arbitrary HasJsonEncodingSpec or HasJsonDecodingSpec instances break when the members of the recursive cycle change, causing a new choice about where to place the Ref.

Directly decode some JSON accoring to a spec without going through any To/FromJSON instances.

Given a raw Haskell structure, directly encode it directly into an aeson Value without having to go through any To/FromJSON instances.

See also: eitherDecode.

JSONStructure spec is the Haskell type used to contain the JSON data that will be encoded or decoded according to the provided spec.

Basically, we represent JSON objects as "list-like" nested tuples of the form:

(Field @key1 valueType,
(Field @key2 valueType,
(Field @key3 valueType,
())))

Note! "Object structures" of this type have the appropriate HasField instances, which allows you to use -XOverloadedRecordDot to extract values as an alternative to pattern matching the whole tuple structure when building your HasJsonDecodingSpec instances. See TestHasField in the tests for an example

Arrays, booleans, numbers, and strings are just Lists, Bools, Scientifics, and Texts respectively.

If the user can convert their normal business logic type to/from this tuple type, then they get a JSON encoding to/from their type that is guaranteed to be compliant with the Specification

Analog of FromJSON, but specialized for decoding our "json representations", and closed to the user because the haskell representation scheme is fixed and not extensible by the user.

We can't just use FromJSON because the types we are using to represent "json data" (i.e. the JSONStructure type family) already have ToJSON instances. Even if we were to make a bunch of newtypes or whatever to act as the json representation (and therefor also force the user to do a lot of wrapping and unwrapping), that still wouldn't be sufficient because someone could always write an overlapping (or incoherent) ToJSON instance of our newtype! This way we don't have to worry about any of that, and the types that the user must deal with when implementing fromJSONRepr can be simple tuples and such.

This is like ToJSON, but specialized for our custom "json representation" types (i.e. the JSONStructure type family). It is also closed (i.e. not exported, so the user can't add instances), because our json representation is closed.

see StructureFromJSON for an explaination about why we don't just use ToJSON.