An encoding between an OCaml data type (the parameter) and a JSON representation. To be built using the predefined combinators provided by this module.

For instance, here is an encoding, of type (int * string) encoding, mapping values of type int * string to JSON objects with a field code of whose value is a number and a field message whose value is a string.

let enc = obj2 (req "code" int) (req "message" string)

This encoding serves three purposes:

1. Output an OCaml value of type 'a to an intermediate JSON representation using construct. To be printed to actual JSON using an external library. 2. Input a JSON intermediate structure (already parsed with an external library) to produce an OCaml value of type 'a. 3. Describe this encoding in JSON-schema format for inter-operability: you describe the encoding of your internal types, and obtain machine-readable descriptions of the formats as a byproduct. Specific documentation combinators are provided for that purpose.

By default, this library provides functions that work on the Json_repr.ezjsonm data type, compatible with Ezjsonm.value. However, encodings are not tied with this representation. See functor Make and module Json_repr for using another format.

Builds a json value from an OCaml value and an encoding.

The optional argument ?include_default_fields allows to systematically manage the behaviour of ?construct argument of dft fields.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

The type of json lexeme. This type is compatible with Jsonm.lexeme

Builds a lazy Seq representation of the OCaml value.

Converts json AST (ezjsonm) into a sequence representation

Reads an OCaml value from a JSON value and an encoding. May raise Cannot_destruct.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

• parameter [ignore_extra_fields]

  (default to false), when true, the extra fields of an object will be ignored during parsing. If set to false, will raise Cannot_destruct (path, Unexpected_field field) instead.

• parameter [bson_relaxation]

  (default to false) works around a limitation of the BSON format. Specifically, in BSON, arrays are represented as number-indexed objects. When nested deep inside a value, arrays and objects are tagged to distinguish them, but at the top-level. However, at the top-level this is not the case. As a result, it is impossible to disintguish a naked array from a naked object.

An encoding of an OCaml unit by any (ignored) JSON.

An encoding of an OCaml unit by a JSON null.

An encoding of an OCaml unit by an empty JSON object.

An encoding of an OCaml int by a JSON number.

When destructing, the JSON number cannot have a fractional part, and must be between -2^30 and 2^30-1 (these bounds are chosen to be compatible with both 32-bit and 64bit native OCaml compilers as well as JavaScript). When constructing, the value coming from the OCaml world is assumed to be valid, otherwise an Invalid_argument will be raised (can only happen on 64-bit systems).

Use int32 or int53 for a greater range. Use ranged_int to restrict to an interval.

An encoding of an OCaml int32 by a JSON number.

Must be a floating point without fractional part and between -2^31 and 2^31-1 when destructing. Never fails when constructing, as all 32-bit integers are included in JSON numbers.

An encoding of a JSON-representable OCaml int64 by a JSON number.

Restricted to the -2^53 to 2^53 range, as this is the limit of representable integers in JSON numbers. Must be a floating point without fractional part and in this range when destructing. When constructing, the value coming from the OCaml world is assumed to be in this range, otherwise an Invalid_argument will be raised.

An encoding of an OCaml int by a JSON number restricted to a specific range.

The bounds must be between -2^30 and 2^30-1.

The inclusive bounds are checked when destructing. When constructing, the value coming from the OCaml world is assumed to be within the bounds, otherwise an Invalid_argument will be raised. The string parameter is a name used to tweak the error messages.

An encoding of an OCaml int32 by a JSON number restricted to a specific range.

The bounds must be between -2^31 and 2^31-1.

The inclusive bounds are checked when destructing. When constructing, the value coming from the OCaml world is assumed to be within the bounds, otherwise an Invalid_argument will be raised. The string parameter is a name used to tweak the error messages.

An encoding of an OCaml int64 by a JSON number restricted to a specific range.

The bounds must be between -2^53 and 2^53.

The inclusive bounds are checked when destructing. When constructing, the value coming from the OCaml world is assumed to be within the bounds, otherwise an Invalid_argument will be raised. The string parameter is a name used to tweak the error messages.

An encoding of an OCaml boolean by a JSON one.

An encoding of an OCaml string by a JSON one.

An encoding of a closed set of OCaml values by JSON strings.

An encoding of a constant string.

An encoding of an OCaml mutable string by a JSON string.

An encoding of an OCaml float by a JSON number.

An encoding of an OCaml float by a JSON number with range constraints

An encoding of an OCaml option by a nullable JSON value. Raises Invalid_argument when nesting options – i.e., when building 'a option option encoding. Also raises Invalid_argument when used on the encoding of null.

A first class handle to a JSON field.

A required field of a given its type.

An optional field of a given type, using an OCaml option.

An optional field of a given type. The field is omitted when equal to the default value except when construct is true.

• parameter [equal]

  defaults to the polymorphic, structural equality (( = )). You must set this function if the type of data carried by the field is not comparable (e.g., a Seq.t).

An encoding of an OCaml value by a singleton object.

An encoding of an OCaml pair by a JSON object with two fields.

An encoding of an OCaml triple by a JSON object with three fields.

An encoding of an OCaml quadruple by a JSON object with four fields.

An encoding of an OCaml quintuple by a JSON object with five fields.

An encoding of an OCaml sextuple by a JSON object with six fields.

An encoding of an OCaml septuple by a JSON object with seven fields.

An encoding of an OCaml octuple by a JSON object with eight fields.

An encoding of an OCaml nonuple by a JSON object with nine fields.

An encoding of an OCaml decuple by a JSON object with ten fields.

Merge two object encodings. For describing heavyweight objects with a lot of fields. The ocaml type is a pair of tuples, but the JSON object is flat. Both arguments must be object encodings, otherwise a future construct, destruct or schema will fail with Invalid_argument.

An encoding of an OCaml array by a JSON one.

An encoding of an OCaml list by a JSON array.

An encoding of an OCaml Seq.t by a JSON array.

The JSON form is indistinguishable from that of a list. In other words, construct (list e) (List.of_seq s) is the same JSON value as construct (seq e) s.

In case you use construct_seq, the elements sequence is traversed lazily as needed.

An encoding of an OCaml associative list by a JSON object.

An encoding of an OCaml value by a singleton array.

An encoding of an OCaml pair by a JSON array with two cells.

An encoding of an OCaml triple by a JSON array with three cells.

An encoding of an OCaml quadruple by a JSON array with four cells.

An encoding of an OCaml quintuple by a JSON array with five cells.

An encoding of an OCaml sextuple by a JSON array with six cells.

An encoding of an OCaml septuple by a JSON array with seven cells.

An encoding of an OCaml octuple by a JSON array with eight cells.

An encoding of an OCaml nonuple by a JSON array with nine cells.

An encoding of an OCaml decuple by a JSON array with ten cells.

Merge two tuple encodings. For describing heavyweight arrays with a lot of cells. The ocaml type is a pair of tuples, but the JSON array is flat, with the elements of the first tuple before the ones of the second. Both arguments must be tuple encodings, otherwise a future construct, destruct or schema will fail with Invalid_argument.

A case for describing union types using union ans case.

To be used inside a union. Takes a encoding for a specific case, and a converter to and from a type common to all cases ('t). Usually, it consists in boxing / deboxing the specific data in an OCaml sum type constructor.

A utility to build destructors for custom encoded sum types.

A simple custom encoding using the Json_repr.ezjsonm intermediate representation for the conversion functions. The resulting encoding is usable with any other instanciation of functor Make, internal conversions may be performed needed. The second transformer function can raise (Cannot_destruct ([ (* location *)], exn)) to indicate an error, which will be relocated correctly.

An encoding adapter, with an optional handwritten schema. The second transformer function can raise (Cannot_destruct ([], exn)) to indicate an error, which will be relocated correctly.

A fixpoint combinator. Links a recursive OCaml type to an internal JSON schema reference, by allowing to use the encoding inside its own definition. The first parameter is a path, that must be unique and respect the format of Json_schema.add_definition. It is used to encode the recursivity as a named reference in the JSON schema.

Here is an example to turn a standard OCaml list into either "nil" for [] or {"hd":hd,"tl":tl} for hd::tl.

let reclist item_encoding =
   mu "list" @@ fun self ->
   union [
      case (string_enum [ "nil", () ])
         (function [] -> Some () | _ :: _ -> None)
         (fun () -> []) ;
      case (obj2 (req "hd" itemencoding) (req "tl" self))
         (function hd :: tl -> Some (hd, tl) | [] -> None)
         (fun (hd, tl) -> hd :: tl)
   ]

Notice that the function passed to mu must be pure. Otherwise, the behavior is unspecified.

A stateful recursive encoding can still be put under a delayed combinator to make sure that a new encoding is generated each time it is used. Caching the encoding generation when the state has not changed is then the responsability of the client.

A raw JSON value in ezjsonm representation.

A valid JSON document (i.e. an array or object value).

A valid JSON object. May raise Unexpected. Specifically, the construct or destruct (or similar) function using this encoding will raise Unexpected if given anything other than an object to handle.

A valid JSON object in ezjsonm representation. May raise Unexpected. Specifically, the construct or destruct (or similar) function using this encoding will raise Unexpected if given anything other than an object to handle.

The encoding of a JSON schema, linked to its OCaml definiton.

Describe an encoding in JSON schema format. May raise Bad_schema.

Name a definition so its occurences can be shared in the JSON schema. The first parameter is a path, that must be unique and respect the format of Json_schema.add_definition.

Exception raised by destructors, with the location in the original JSON structure and the specific error.

Unexpected kind of data encountered (w/ the expectation).

Some union couldn't be destructed, w/ the reasons for each case.

Array of unexpected size encountered (w/ the expectation).

Missing field in an object.

Supernumerary field in an object.

Bad custom schema encountered.

Produces a human readable version of an error.

Custom encoders for an OCaml type, given both custom conversion functions. The actual representation is not known in advance, so the conversion functions have to examine / construct the JSON value through the first class modules they are passed. The read transformer function can raise (Cannot_destruct ([], "message")) to indicate an error, which will be relocated correctly.

Here is an example of how to build such a value for a type 't.

 let read
     : type tf. (module Json_repr.Repr with type value = tf) -> tf -> 't
     = fun (module Repr_f) repr ->
       match Repr_f.view repr with
       | `Null (* destruct the JSON using [Repr_f.view] *) ->
         (* create a value of type 't *)
       | _ ->
         (* or fail with this wrapping exception *)
         raise (Cannot_destruct ([ (* location *) ], (* exn *))) in
   let write
     : type tf. (module Json_repr.Repr with type value = tf) -> 't -> tf
     = fun (module Repr_f) v ->
       (* examine the value and produce a JSON using [Repr_f.repr] *)
       Repr_f.repr `Null in
   { read ; write } 

A custom encoding, using custom encoders and a schema.

A raw JSON value in its original representation.

Returns true is the encoding might construct null.