Module Jsont

Types for JSON values.

This module provides a type for describing JSON values as a bidirectional map between subset of JSON values and arbitrary OCaml values. We call these values JSON types.

In these maps we call decoding the direction from JSON values to OCaml values and encoding the direction from OCaml values to JSON values. Depending on your usage one direction or the other can be left unspecified. Some of the maps may be lossy or creative which leads to JSON queries and transforms.

See the quick start and the cookbook.

Preliminaries

type 'a fmt = Stdlib.Format.formatter -> 'a -> unit

The type for formatters of type 'a.

module Textloc : sig ... end

Text locations.

module Meta : sig ... end

Node metadata.

type 'a node = 'a * Meta.t

The type for JSON nodes. The data of type 'a and its metadata.

module Sort : sig ... end

JSON sorts.

module Path : sig ... end

JSON paths.

module Context : sig ... end

JSON encoding and decoding contexts.

module Error : sig ... end

Encoding, decoding and query errors.

exception Error of Error.t

The exception for errors.

Types

type 'a t

The type for a subset of JSON values represented by OCaml values of type 'a.

val kind : 'a t -> string

kind t is a human readable string describing the JSON values typed by t.

val doc : 'a t -> string

doc t is a documentation string for the JSON values typed by t.

val rec' : 'a t Stdlib.Lazy.t -> 'a t

rec' is used to for recursive descriptions.

Base types

module Base : sig ... end

JSON base type maps.

val null : ?kind:string -> ?doc:string -> 'a -> 'a t

null v represents JSON nulls by the value v. On encodes any value of type 'a is encoded by null. doc and kind are given to the underlying Base.map. See also Base.null.

val bool : bool t

bool represents JSON booleans by bool values. See also Base.bool.

val number : float t

number represents JSON nulls or numbers by float values. On decodes JSON null is mapped to Float.nan. On encodes any non-finite float is lossily mapped to JSON null (explanation). See also Base.number or any_float.

val string : string t

string represents JSON strings by unescaped and UTF-8 encoded string values. See also Base.string.

Warning. On encodes OCaml strings are not checked for UTF-8 validity.

Arrays

module Array : sig ... end

JSON array maps.

val array' : ('a, 'elt, 'b) Array.map -> 'a t

array' map represents JSON arrays with arrays of type 'a. See the array combinators.

Objects

module Obj : sig ... end

JSON object maps.

Any

val any : ?kind:string -> ?doc:string -> ?dec_null:'a t -> ?dec_bool:'a t -> ?dec_number:'a t -> ?dec_string:'a t -> ?dec_array:'a t -> ?dec_obj:'a t -> ?enc:(Context.t -> 'a -> 'a t) -> unit -> 'a t

any () is any JSON value represented by the cases given explicitely. The unspecified case are not represented and error for encoding and decoding. enc is used to select the type on encoding and can be omitted if the result is only used for decoding. kind is the kind of JSON value represented and doc a documentation string.

Maps

val map : ?kind:string -> ?doc:string -> ?dec:(Context.t -> 'a -> 'b) -> ?enc:(Context.t -> 'b -> 'a) -> 'a t -> 'b t

map ~kind ~doc ~dec ~enc t changes the representation 'a of t to 'b.

  • kind names the entities represented by type 'b. Defaults to "".
  • doc is a documentation string for kind. Defaults to "".
  • dec is used to decode values of type 'a to values of type 'b. Can be omitted if the result is only used for encoding. The default unconditionally errors.
  • enc is used to encode values of type 'b to values of type 'a. Can be omitted if the result is only used for decoding in which case the default unconditionally errors.

Derived types

val ignore : unit t

ignore lossily represents all values by (). It errors on encoding.

val todo : ?kind:string -> ?doc:string -> unit -> 'a t

todo () represents any JSON by nothing. It fails in every direction.

Options

val none : 'a option t

none represents JSON nulls by None.

val some : 'a t -> 'a option t

some t represents like t but wraps decoded values in Some. Encoding fails if the value is None.

val option : ?kind:string -> ?doc:string -> 'a t -> 'a option t

option t represents JSON nulls by None and other values by t.

Integers

See this note about (not) representing integers by JSON number values.

val int : int t

int represents truncated JSON numbers or JSON strings by int values.

  • JSON numbers are sucessfully decoded if after truncation they can be represented on the int range, otherwise the decoder errors. int values are encoded as JSON numbers if the integer is in the [-253;253] range.
  • JSON strings are decoded using int_of_string_opt, this allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. int values are encoded as JSON strings with Int.to_string when the integer is outside the [-253;253] range
val uint8 : int t

uint8 represents JSON numbers by unsigned 8-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [0;255] range. Encoding errors if the integer is out of range.

val uint16 : int t

uint16 represents JSON numbers by unsigned 16-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [0;65535] range. Encoding errors if the integer is out of range.

val int8 : int t

int8 represents JSON numbers by 8-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [-128;127] range. Encoding errors if the integer is out of range.

val int16 : int t

int16 represents JSON numbers by 16-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [-32768;32767] range. Encoding errors if the integer is out of range.

val int32 : int32 t

int32 represents JSON numbers by 32-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the int32 range, otherwise the decoder errors.

val int64 : int64 t

int represents truncated JSON numbers or JSON strings by 64-bit integers.

  • JSON numbers are sucessfully decoded if after truncation they can be represented on the int64 range, otherwise the decoder errors. int64 values are encoded as JSON numbers if the integer is in the [-253;253] range.
  • JSON strings are decoded using int_of_string_opt, this allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. int values are encoded as JSON strings with Int.to_string when the integer is outside the [-253;253] range
val int_as_string : int t

int_as_string represents JSON strings by int values. On decodes this uses int_of_string_opt which allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. On encodes uses Int.to_string.

val int64_as_string : int64 t

int64_as_string represents JSON strings by 64-bit integers. On decodes this uses Int64.of_string_opt which allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. On encodes uses Int.to_string.

Floats

val any_float : float t

any_float is a lossless representation for IEEE 754 doubles. It represents non-finite floats by the JSON strings defined by Float.to_string. This contrasts with number which maps them to JSON null values (explanation). Note that on decodes this still maps JSON nulls to Float.nan. On decoding strings it accepts anything successful decode of Float.of_string_opt. See also number.

Warning. any_float should only be used between parties that have agreed on such an encoding. To maximize interoperability you should use the lossy number map.

val float_as_hex_string : float t

float_as_hex_string represents JSON strings by IEEE 754 doubles in hex notation ("%h" format string). On decodes it accepts anything sucessfully decoded by Float.of_string_opt.

Strings and enums

val enum : ?cmp:('a -> 'a -> int) -> ?kind:string -> ?doc:string -> (string * 'a) list -> 'a t

enum assoc represents JSON strings member of the assoc list by the corresponding OCaml value. cmp is used to compare the OCaml values, it defaults to Stdlib.compare. Decoding and encoding error on strings or values not part of assoc.

Arrays and tuples

val list : ?kind:string -> ?doc:string -> 'a t -> 'a list t

list t represents JSON arrays of type t by list values. This is array' (Array.list t).

val array : ?kind:string -> ?doc:string -> 'a t -> 'a array t

array t represents JSON arrays of type t by array values. This is array' (Array.array t).

val bigarray : ?kind:string -> ?doc:string -> ('a, 'b) Bigarray.kind -> 'a t -> ('a, 'b, Bigarray.c_layout) Bigarray.Array1.t t

bigarray k t represents JSON arrays of type t with Bigarray.Array1.t values. This is array' (Array.bigarray t).

val t2 : ?kind:string -> ?doc:string -> ?dec:('a -> 'a -> 't2) -> ?enc:('t2 -> int -> 'a) -> 'a t -> 't2 t

t2 ?enc ?dec t represents JSON arrays with exactly 2 elements of type t by 't2. Decodes error if there are more elements.

val t3 : ?kind:string -> ?doc:string -> ?dec:('a -> 'a -> 'a -> 't3) -> ?enc:('t3 -> int -> 'a) -> 'a t -> 't3 t

t3 is like t2 but for 3 elements.

val t4 : ?kind:string -> ?doc:string -> ?dec:('a -> 'a -> 'a -> 'a -> 't4) -> ?enc:('t4 -> int -> 'a) -> 'a t -> 't4 t

t4 is like t2 but for 4 elements.

Generic JSON

module Json : sig ... end

Generic JSON values and types.

Queries

module Caret : sig ... end

JSON carets

module Query : sig ... end

JSON queries.

Low-level representation

module Repr : sig ... end

Low level representation (unstable).