Documentation

A combined JSON encoder-decoder with associated documentation.

A value of type 'SchemaP d v w a b', which we will refer to as a schema, contains both a JSON parser and a JSON serialiser, together with documentation-like metadata, such as a JSON or Swagger schema.

The type variables are as follows:

d

documentation type, usually a Monoid.

v

type of JSON values being parsed (e.g. Value).

w

type of JSON values being serialised (e.g. Value).

a

input type

b

output type

Input and output types deserve some more explanation. We can think of a value sch of type 'SchemaP d v w a b' as a kind of special "function" from a to b, but where a and b might potentially live in different "languages". The parser portion of sch takes a JSON-encoded value of type a and produces a value of type b, while the serialiser portion of sch takes a haskell value of type a and produces a JSON-encoding of something of type b.

In terms of composability, this way of representing schemas (based on input and output types) is superior to the perhaps more natural approach of using "bidirectional functions" or isomorphisms (based on a single type parameter).

Although schemas cannot be composed as functions (i.e. they do not form a Category), they still admit a number of important and useful instances, such as Profunctor (and specifically Choice), which makes it possible to use prism quite effectively to build schema values.

Using type variables to represent JSON types might seem like excessive generality, but it is useful to represent "intermediate" schemas arising when building complex ones. For example, a schema which is able to work with fields of a JSON object (see field) should not output full-blown objects, but only lists of pairs, so that they can be combined correctly via the usual Monoid structure of lists when using the Applicative interface of 'SchemaP d v w a b'.

The idea of using the profunctor structure of SchemaP is taken from the codec library.

A type with a canonical typed schema definition.

Using ToSchema, one can split a complicated shema definition into manageable parts by defining instances for the various types involved, and using the schema method to reuse the previously-defined schema definitions for component types.

Build a schema from documentation, parser and serialiser

A schema for a JSON object.

This can be used to convert a combination of schemas obtained using field into a single schema for a JSON object.

Like object, but apply an arbitrary function to the documentation of the resulting object.

A version of object for more general input values.

Just like fieldOver, but for object.

A schema for an arbitrary JSON object.

A schema for an arbitrary JSON value.

A schema for a one-field JSON object.

Like field, but apply an arbitrary function to the documentation of the field.

Like fieldOverF, but specialised to the identity functor.

A schema for a JSON object with a single optional field.

Like optField, but apply an arbitrary function to the documentation of the field.

Generalization of optField with FieldFunctor.

A version of field for more general input values.

This can be used when the input type v of the parser is not exactly a Object, but it contains one. The first argument is a lens that can extract the Object contained in v.

See bind for use cases.

Like fieldF, but apply an arbitrary function to the documentation of the field.

A schema for a JSON array.

A schema for a JSON object with arbitrary keys of type k. The type of keys must have instances for FromJSONKey and ToJSONKey.

Use mapWithKeys for key types that do not have such instances.

A schema for a JSON object with arbitrary keys of type k, where k can be converted to and from Text.

A schema for a JSON enumeration.

This is used to convert a combination of schemas obtained using element into a single schema for a JSON string.

A schema for Maybe that omits a field on serialisation.

This is most commonly used for optional fields, and it will cause the field to be omitted from the output of the serialiser.

A schema for Maybe, producing the given default value on serialisation.

A schema depending on a parsed value.

Even though SchemaP does not expose a monadic interface, it is possible to make the parser of a schema depend on the values parsed by a previous schema.

For example, a schema for an object containing a "type" field which determines how the rest of the object is parsed. To construct the schema to use as the second argument of bind, one can use dispatch.

A union of schemas over a finite type of "tags".

Normally used together with bind to construct schemas that depend on some "tag" value.

A schema for a textual value.

A schema for a textual value with possible failure.

A schema for a null value.

A schema for a nullable value.

The parser accepts a JSON null as a valid value, and converts it to Nothing. Any non-null value is parsed using the underlying schema.

The serialiser behaves similarly, but in the other direction.

A schema for a single value of an enumeration.

Change the input and output types of a schema via a prism.

Turn a named schema into an unnamed one.

This is mostly useful when using a schema as a field of a bigger schema. If the inner schema is unnamed, it gets "inlined" in the larger scheme definition, and otherwise it gets "referenced". This combinator makes it possible to choose one of the two options.

Attach a name to a schema.

This only affects the documentation portion of a schema, and not the parsing or serialisation.

Change the input type of a schema.

JSON serialiser for an instance of ToSchema.

JSON parser for an instance of ToSchema.