package ppx_deriving_encoding

Json_encoding Ppx deriver

ppx_deriving_encoding is a json-encoding ppx deriver.

type x = {
    a : string;
    b : int list;
    c : Ezjsonm.value option;
}
[@@deriving json_encoding]

will produce the encoding:

let x_enc : x encoding =
  conv
    (fun {a; b; c} -> (a, b, c))
    (fun (a, b, c) -> {a; b; c})
    (obj3
      (req "a" string)
      (req "b" (list int))
      (opt "c" any_ezjson_value))

Most of regular json types are handled. GADT and variant inheritance are not handled yet.

Field Options

• [@req] Nullable field instead of an undefined (opt)

    a : x option [@req]
  

  will produce a field :

    (req "a" (option x_enc))
  

• [@dft expr] Default field instead

    a : x [@dft expr]
  

  will produce a field :

    (dft "a" x_enc expr)
  

• [@key "name"] Specify the name of the field

     a : x [@key "name"]
  

  will produce a field :

    (req "name" x_enc)
  

• [@title expr] Specify the title of the field

     a : x [@title expr]
  

  will produce a field :

    (req ~title:expr "a" x_enc)
  

• [@description expr] Specify the description of the field

     a : x [@description expr]
  

  will produce a field :

    (req ~description:expr "a" x_enc)
  

• [@exclude expr] Exclude a field from an encoding

    {
      a : x;
      b : y; [@exclude y_default]
      c : z;
    }
  

  will produce :

    conv
        (fun {a; _; c} -> (a, c))
        (fun (a, c) -> {a; b = y_default; c})
        (obj2
            (req "a" x_enc)
            (req "c" z_enc))
  

• [@merge] Merge an field object instead of creating another field

    {
      a : x; [@merge]
      b : z;
    }
  

  will produce :

    conv
        (fun {a; _; c} -> (a, c))
        (fun (a, c) -> {a; b = y_default; c})
        (merge_objs x_enc (obj1 (req "c" z_enc)))
  

General options

• [@assoc]

  Create an assoc encoding

    (string * x) list [@assoc]
  

  will produce :

    assoc x_enc
  

• [@enum]

  Create an string enum encoding

    [ `A | `B | `C ]
  

  will produce :

    string_enum [ "a", `A ; "b" `B; "c", `C ]
  

  For normal type constructor, you need to use the flag attribute:

    type t = A | B | C [@@deriving json_encoding {enum}]
  

• [@encoding expr]

  Assign a generic encoding

• [@obj1 "name"]

  Wrap an encoding inside a obj1 encoding

Tuple options

• [@object]

  Create an object encoding from a tuple

    ( w, x [@exclude x_default], y [@key "name"], z ) [@object]
  

  will produce:

    conv
      (fun (w, _, y, z) -> (w, y, z))
      (fun (w, y, z) -> (w, x_default, y, z))
      (obj3
        (req "0" w_enc)
        (req "name" y_enc)
        (req "3" z_enc))
  

Variant options

If it is not a string enumeration, any constructor or polymorphic variant will produce a union encoding. Any case of the union can receive [@title expr], [@description expr], [@kind "kind"] attributes.

[@kind "kind_name"] will add the encoding

(obj1 (req "kind" (constant "kind_name")))

to allow several constructor with the same type to be well desctructed.

type t =
    | A of x [@kind "a"]
    | B of y
    | C of x [@kind "c"] [@@deriving json_encoding]

will produce :

let enc =
  union [
    case
      (conv (fun x -> (), x) (fun ((), x) -> x)
        (merge_objs (obj1 (req "kind" (constant "a"))) x_enc))
      (function A x -> Some x | _ -> None)
      (fun x -> A x);
    case
      y_enc
      (function B x -> Some x | _ -> None)
      (fun x -> B x);
    case
      (conv (fun x -> (), x) (fun ((), x) -> x)
        (merge_objs (obj1 (req "kind" (constant "c"))) x_enc))
      (function C x -> Some x | _ -> None)
      (fun x -> C x);
  ]

Top type options

• ignore

  wrap an object encoding to ignore other fields

    type t = {
        a : x;
        b : y;
    } [@@deriving json_encoding {ignore}]
  

  will produce :

    let enc =
      conv
        (fun x -> (), x)
        (fun ((), x) -> x)
        (merge_objs
          unit
          (conv
            (fun {a; b} -> (a, b))
            (fun (a, b) -> {a; b})
            (obj2
              (req "a" x_enc)
              (req "b" y_enc))))
  

  It can also be used as an attribute for records in constructor:

    type x =
        | A of { a : y } [@ignore]
        | B of t
  

• remove_prefix

  Remove prefixes of record

    type x = {
        x_a : a;
        b : b;
    } [@@deriving json_encoding {remove_prefix="true"}]
  

  will produce :

    let x_enc =
      conv
        (fun {x_a; b} -> (x_a, b))
        (fun (x_a, b) -> {x_a; b})
        (obj2
          (req "a" a_enc)
          (req "b" b_enc))
  

  When all the record fields have the same prefix they will be automatically removed. This automatic removing can be cancelled by [@@deriving json_encoding {remove_prefix="false"}]

• recursive

  Wrap an encoding in a recursive construction

    type x =
      | A of x
      | B [@@deriving json_encoding {recursive}]
  

  will produce :

    let x_enc x_enc =
      union [
        case x_enc (function A x -> Some x | _ -> None) (fun x -> A x);
        case empty (function B -> Some () | _ -> None) (fun () -> B)
      ]
  

• title, description

  Wrap en encoding to add some description

    type x = y [@@deriving json_encoding {title = "title"; description = "descr"}]
  

  will produce :

    let x_enc =
      def "x" ~title:"title" ~description:"descr" y_enc
  

• schema

  Wrap an encoding to add a schema

    type x = y [@@deriving json_encoding {schema = sch}]
  

  will produce :

    let x_enc =
      conv (fun x -> x) (fun x -> x)
        ~schema:sch y_enc
  

• option

  Choose the default option handling

    type x = {
      a : string option
    }[@@deriving json_encoding {option = "req"}]
  
    type y = {
      a : string option
    }[@@deriving json_encoding {option = "opt"}]
  
    type z = {
      a : string option
    }[@@deriving json_encoding {option = "dft"}]
  

  will produce :

    let x_enc = obj1 (req "a" (option string))
    let y_enc = obj1 (opt "a" string)
    let z_enc = obj1 (dft "a" (option string) None)
  

  The default one is dft which handles both null and undefined but will give an error at runtime if the following encoding is nullable.

• debug

  Force the printing of the produced encoding during compilation