OCaml serializing a (no args) variant as a "string enum" (via Yojson)

Say I am building a record type:

type thing {
  fruit: string;
}

But I want the possible values of fruit to be constrained to a fixed set of strings.

It seems natural to model this in OCaml as a variant, e.g.:

type fruit = APPLE | BANANA | CHERRY

type thing {
  fruit: fruit;
}

Okay so far.

But if I use [@@deriving yojson] on these types then the serialized output will be like:

{ "fruit": ["APPLE"] }

By default Yojson wants to serialize a variant as a tuple of [<name>, <args>...] which... I can see the logic of it, but it is not helpful here.

I want it to serialize as:

{ "fruit": "APPLE" }

Making use of a couple of ppx deriving plugins I managed to build this module to de/serialize as I want:

module Fruit = struct
  type t = APPLE | BANANA | CHERRY [@@deriving enum, variants]

  let names =
    let pairs i (name, _) = (name, (Option.get (of_enum i))) in
    let valist = List.mapi pairs Variants.descriptions in
    List.to_seq valist |> Hashtbl.of_seq
  
  let to_yojson v = `String (Variants.to_name v)

  let of_yojson = function
    | `String s -> Hashtbl.find_opt names s
                   |> Option.to_result ~none:(Printf.sprintf "Invalid value: %s" s)
    | yj -> Error (Printf.sprintf "Invalid value: %s" (Yojson.Safe.to_string yj))
end

Which works fine... but I have some other "string enum" variants I want to treat the same way. I don't want to copy and paste this code every time.

I got as far as this:

module StrEnum (
  V : sig
    type t
    val of_enum : int -> t option
    module Variants : sig
      val descriptions : (string * int) list
      val to_name : t -> string
    end
  end
) = struct  
  type t = V.t

  let names =
    let pairs i (name, _) = (name, (Option.get (V.of_enum i))) in
    let valist = List.mapi pairs V.Variants.descriptions in
    List.to_seq valist |> Hashtbl.of_seq
  
  let to_yojson v = `String (V.Variants.to_name v)

  let of_yojson = function
    | `String s -> Hashtbl.find_opt names s
                  |> Option.to_result ~none:(Printf.sprintf "Invalid StrEnum value: %s" s)
    | yj -> Error (Printf.sprintf "Invalid StrEnum value: %s" (Yojson.Safe.to_string yj))
end

module Fruit = struct
  type t = APPLE | BANANA | CHERRY [@@deriving enum, variants]
end

module FruitEnum = StrEnum (Fruit)

That much seems to type-check, and I can:

utop # Yojson.Safe.to_string (FruitEnum.to_yojson Fruit.APPLE);;
- : string = "\"APPLE\""

utop # FruitEnum.of_yojson (Yojson.Safe.from_string "\"BANANA\"");;
- : (FruitEnum.t, string) result = Ok Fruit.BANANA

...but when I try to:

type thing {
  fruit: FruitEnum.t;
}
[@@deriving yojson]

I get Error: Unbound value FruitEnum.t

It seems to be because I am re-exporting type t = V.t from the variant's module, I don't really understand though. (Or is it because the yojson ppx can't "see" the result of the functor properly?)
How can I fix this?

I would also like to be able to skip defining the variant module separately and just do:

module Fruit = StrEnum (struct
  type t = APPLE | BANANA | CHERRY [@@deriving enum, variants]
end)

...but this gives the error:

Error: This functor has type
       functor
         (V : sig
                type t
                val of_enum : int -> t option
                module Variants :
                  sig
                    val descriptions : (string * int) list
                    val to_name : t -> string
                  end
              end)
         ->
         sig
           type t = V.t
           val names : (string, t) Hashtbl.t
           val to_yojson : t -> [> `String of string ]
           val of_yojson : Yojson.Safe.t -> (t, string) result
         end
       The parameter cannot be eliminated in the result type.
       Please bind the argument to a module identifier.

and I don't understand what is wrong.

Regarding the last error, it's because OCaml requires a 'stable path' to types inside modules so it can refer to them. A stable path is a named path to a type, e.g. Fruit.t.

By contrast, StrEnum(struct type t = ... end).t is not a stable path because the type t is referencing a type t in the module literal which does not have a name.

Long story short, you basically can't skip defining the variant module separately. But it's simple to do it in two steps:

module Fruit = struct
  type t = ...
end

module Fruit = StrEnum(Fruit)

The second definition refers to the first and shadows it. Shadowing is a well-known and often-used technique in OCaml.

Overall, I'm not sure all this PPX machinery is actually justified. You can pretty easily hand-write converter functions, e.g.

let to_yojson = function
  | APPLE -> `String "APPLE"
  | BANANA -> `String "BANANA"
  | CHERRY -> `String "CHERRY"