A JSON encoding combinator for a value of type 'a.

to_value_exn encoding value encodes value in JSON using encoding. Will raise an exception in case encoding cannot serialize value.

  open Ezjsonm_encoding

  let encoding = obj1 (req "hello" string)

  let json = to_value_exn encoding "world"
    (* `O [("hello", `String "world")] *)

to_value_exn encoding value encodes value in JSON using encoding. Will return None in case encoding cannot serialize value.

to_string_exn ~minify encoding value encodes value using encoding into a JSON value serialized in a string. Will raise an exception in case encoding cannot serialize value.

to_string ~minify encoding value encodes value using encoding into a JSON value serialized in a string. Will return None in case encoding cannot serialize value.

from_string_exn encoding str decodes a JSON value from str, then uses encoding to construct an OCaml value. Will raise an exception if str is not a valid JSON value, or if encoding cannot construct an OCaml value from str.

from_string encoding str decodes a JSON value from str, then uses encoding to construct an OCaml value. Will return None if str is not a valid JSON value, or if encoding cannot construct an OCaml value from str.

from_value_exn encoding value uses encoding to construct an OCaml value from value. Will raise an exception if encoding cannot construct an OCaml value from value.

from_string encoding str decodes a JSON value from str, then uses encoding to construct an OCaml value. Will return None if str is not a valid JSON value, or if encoding cannot construct an OCaml value from str.

The identity encoding.

conv f g encoding crafts a new encoding from encoding. This is typically used to creates a JSON encoder/decoder for OCaml records by projecting them to tuples, and using objN combinators.

  open Ezjsonm_encoding

  type t = { f1 : int; f2 : bool }

  let encoding =
    conv
      (fun { f1; f2 } -> (f1, f2))
      (fun (f1, f2) -> { f1; f2 })
      (obj2 (req "f1" int) (req "f2" bool))

  let json = to_value_exn encoding { f1 = 0; f2 = true }
    (* `O [("f2", `Bool true); ("f1", `Float 0.)] *)

string_enum maps JSON strings to fixed OCaml values.

  open Ezjsonm_encoding

  type toggle = On | Off

  let toggle_encoding = string_enum [ "on", On; "off", Off ]

  let json = to_value_exn toggle_encoding On
    (* `String "on" *)

  let toggle = from_string_exn toggle_encoding {|"on"|}
    (* On *)

enum is a more generic version of string_enum, taking an encoder to deal with the supported constant values.

  open Ezjsonm_encoding

  type toggle = On | Off

  let toggle_encoding = enum int [ 1, On; 2, Off ]

  let json = to_value_exn toggle_encoding On
    (* `Float 1. *)

  let toggle = from_string_exn toggle_encoding {|1|}
    (* On *)

constant name maps the JSON string name to (). A typical use case for constant is to tag objects.

  open Ezjsonm_encoding

  let encoding =
    conv
      (fun str -> ((), str))
      (fun ((), str) -> str)
      (obj2
        (req "purpose" (constant "name"))
        (req "value" string))

  let json = to_value_exn encoding "Thomas"
    (* `O [("value", `String "Thomas"); ("purpose", `String "name")] *)

  let value = from_string_exn encoding {|{"purpose": "name", "value": "Thomas"}|}
    (* "Thomas" *)

The encoding which maps JSON strings and OCaml strings.

  open Ezjsonm_encoding

  let json = to_value_exn string "hello, world!"
    (* `String "hello, world!" *)

  let str = from_string_exn string {|"hello, world!"|}
    (* "hello, world!" *)

The encoding which maps JSON ints and OCaml int64. As a reminder, Ezjsonm uses floats internally to encode integers.

  open Ezjsonm_encoding

  let json = to_value_exn int64 1L
    (* `Float 1. *)

  let str = from_string_exn int64 "1"
    (* 1L *)

The encoding which maps JSON ints and OCaml ints. As a reminder, Ezjsonm uses floats internally to encode integers.

  open Ezjsonm_encoding

  let json = to_value_exn int 1
    (* `Float 1. *)

  let str = from_string_exn int "1"
    (* 1 *)

The encoding which maps JSON null and OCaml unit.

  open Ezjsonm_encoding

  let json = to_value_exn null ()
    (* `Null *)

  let str = from_string_exn null "null"
    (* 1 *)

The encoding which maps JSON booleans and OCaml booleans.

  open Ezjsonm_encoding

  let json = to_value_exn bool false
    (* `Bool false *)

  let str = from_string_exn bool "false"
    (* false *)

list encoding creates a encoding for a list of values based on the encoding of said values.

  open Ezjsonm_encoding

  let json = to_value_exn (list bool) [true; true; false]
    (* `A [`Bool true; `Bool true; `Bool false] *)

  let str = from_string_exn (list int) "[1, 2, 3]"
    (* [1; 2; 3] *)

empty maps the empty object to the OCaml unit value. Contrary to obj0, it is strict. That is, objects with fields will be rejected by this encoding.

  open Ezjsonm_encoding

  let json = to_value_exn empty ()
    (* `O [] *)

  let str = from_string_exn empty "{}"
    (* () *)

tup1 f represents an array characterized by the positional (mandatory) element f.

  open Ezjsonm_encoding

  let json = to_value_exn (tup1 int) 1
  (* `A [`Float 1.] *)

tup2 f1 f2 represents an array characterized by two positional (mandatory) elements f1 and f2.

  open Ezjsonm_encoding

  let json = to_value_exn (tup2 int string) (1, "hello")
  (* `A [`Float 1.; `String "hello"] *)

Same as tup2 but with three positional elements.

Same as tup2 but with four positional elements.

Same as tup2 but with five positional elements.

Same as tup2 but with six positional elements.

Same as tup2 but with seven positional elements.

Same as tup2 but with eight positional elements.

Same as tup2 but with nine positional elements.

Same as tup2 but with 10 positional elements.

The description of one field of a JSON object. See req, opt and dft to construct field values, and obj1 to obj10 and merge_objs to construct encoding for objects.

req field_name encoding represents a required field. That is, the decoding will fail if provided an object lacking this field (and raises an exepction with from_string_exn and from_string_exn).

  open Ezjsonm_encoding

  let json = to_value_exn (obj1 (req "hello" string)) "world!"
    (* `O [("hello", `String "world!")] *)

  let str = from_string_exn (obj1 (req "hello" string)) {|{ "hello": "world!"}|}
    (* "world!" *)

  let str = from_string (obj1 (req "hello" string)) {|{ "bye": "world!"}|}
    (* None *)

opt field_name encoding represents an optional field (i.e., wrapped in an option).

If the field is present but cannot be decoded by encoding, then None is returned. This may change in a future version of this library.

  open Ezjsonm_encoding

  let json = to_value_exn (obj1 (opt "hello" string)) (Some "world!")
    (* `O [("hello", `String "world!")] *)

  let json' = to_value_exn (obj1 (opt "hello" string)) None
    (* `O [] *)

  let str = from_string_exn (obj1 (opt "hello" string)) {|{ "hello": "world!"}|}
    (* Some "world!" *)

  let str = from_string (obj1 (opt "hello" string)) {|{ "bye": "world!"}|}
    (* Some None *)

dft field_name encoding default represents an optional field that defaults to default in OCaml if missing. The field is omitted when encoding if the value is equal (according to equal, defaulting to (=)) the default value.

If the field is present but cannot be decoded by encoding, then default is returned. This may change in a future version of this library.

  open Ezjsonm_encoding

  let encoding = obj1 (dft "hello" string "world!")

  let json1 = to_value_exn encoding "friend!"
  (* `O [("hello", `String "friend!")] *)

  let json2 = to_value_exn encoding "world!"
  (* `O [] *)

  let str = from_string_exn encoding {|{ "hello": "Kat!"}|}
  (* "Kat!" *)

obj0 represents the empty object. Since ezjsonm-encoding default behavior is to ignore unspecified fields, obj0 matches any objects. Use empty if you want to reject non-empty objects.

obj1 f represents an object characterized by at least the field f. This field can be optional or required depending on how it has been defined (see req and opt).

obj2 f1 f2 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj3 f1 f2 f3 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj4 f1 f2 f3 f4 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj5 f1 f2 f3 f4 f5 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj6 f1 f2 f3 f4 f5 f6 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj7 f1 f2 f3 f4 f5 f6 f7 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj8 f1 f2 f3 f4 f5 f6 f7 f8 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj9 f1 f2 f3 f4 f5 f6 f7 f8 f9 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

obj10 f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

merg_objs obj1 obj2 represents an object characterized by at least the fields of obj1 and obj2. This is useful when an object expects at least more than 10 fields. Note that it is expected that obj1 and obj2 do not have conflict wrt. field names. This is not checked by ezjsonm-encoding, and is considered an undefined behavior (which may change in a future version of the library).

  open Ezjsonm_encoding

  let json =
    to_value_exn
      (merge_objs
         (obj2 (req "foo" string) (req "bar" bool))
         (obj1 (opt "foobar" int)))
      (("hello", true), Some 1)
    (* `O [("bar", `Bool true); ("foo", `String "hello"); ("foobar", `Float 1.)] *)

case proj inj enc is a partial encoding that can be used to encode and decode a subset of the values of the type domain. It is typically used with union.

union cases is the union of several partial encoding. It can be used to decode and encode algebraic data type. Cases are tried in order, i.e., the first encoding which works is selected.

union is compatible with merge_objs if every encoding in cases matches objects.

  open Ezjsonm_encoding

  type id = Number of int | String of string | Null

  let id_encoding =
    union
      [
        case (function Number i -> Some i | _ -> None) (fun i -> Number i) int;
        case
          (function String s -> Some s | _ -> None)
          (fun s -> String s)
          string;
        case (function Null -> Some () | _ -> None) (fun () -> Null) null;
      ]

  let json = to_value_exn id_encoding (Number 1)
  (* `String "on" *)

  let id = from_string_exn id_encoding {|1|}
  (* Number 1 *)

  let json = to_value_exn id_encoding Null
  (* `Null *)

  let id = from_string_exn id_encoding {|null|}
  (* Null *)

satisfies cond enc restricts the domain of enc to values satisfying cond.

  open Ezjsonm_encoding

  let ranged_int = satisfies (fun i -> 2 < i && i <= 5) int

  let json1 = to_value ranged_int 1
  (* None *)

  let json2 = to_value ranged_int 3
  (* Some (`Float 3) *)