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.

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.

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,
())))

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

This allows for recursive specifications.

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

Using JsonLet prevents the specification type from being infinitely sized, but what about "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 the structure type for your spec requires a self-reference, it will require you to wrap the recursed upon values in this type.

For example:

data Foo = Foo [Foo]
instance HasJsonEncodingSpec Foo where
  type EncodingSpec Foo =
    JsonLet
      '[ '("Foo", JsonArray (JsonRef "Foo")) ]
      (JsonRef "Foo")
  toJSONStructure (Foo fs) = 
    [ Rec (toJSONStructure f)
    | f <- fs
    ]

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

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.

Specify a field in an object.