add a way to use a variant to define a json string instead of a string list

[Khady]

I want to encode three possible string 2025-06-18, 2025-03-26, and 2024-11-05 as a variant. Right now if I use a variant it will be represented in json as a string list. It is fine when transporting internal data, but it isn't great when consuming and interacting with external APIs.

Without adding a different representation for the variant, maybe we can just expose some helpers, a la enum of cmdliner. So instead of

  type protocol_version =
    | V2025_06_18 [@json.name "2025-06-18"]
    | V2025_03_26 [@json.name "2025-03-26"]
    | V2024_11_05 [@json.name "2024-11-05"]
  [@@deriving json]

We would have

type protocol_version =
  | V2025_06_18
  | V2025_03_26 
  | V2024_11_05

let protocol_version_of_json, protocol_version_to_json = Melange_json.Primitives.string_enum [ V2025_06_18, "2025-06-18"; V2025_03_26, "2025-03-26"; V2024_11_05, "2024-11-05" ]

It's not as good as just defining the variant, but maybe an acceptable middle ground.

[andreypopp]

Another alternative is to use some ppx_enum which would map variants to string/ints/... and then a basic to_json/of_json defined manually:

type protocol_version =
  | V2025_06_18 [@enum "2025-06-18"]
  | V2025_03_26 [@enum "2025-06-18"]
  | V2024_11_05 [@enum "2025-06-18"]
  [@@deriving enum]

let protocol_version_to_json v = [%to_json: string] (protocol_version_to_enum v)
let protocol_version_of_json j = protocol_version_to_enum ([%of_json: string] j)

[raphael-proust]

One issue is that a string is valid as part of a json value (e.g., in a field, in an array) but is not a valid json value in and on itself.

See yojson writer doc and specifically the std (standard) parameter:

require the root node to be either an object or an array

And more directly from json specs

JSON is built on two structures:

A collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array.
An ordered list of values. In most languages, this is realized as an array, vector, list, or sequence.

---

There is a similar problem to bracketing when pretty-printing algebra expression: we want x + 3 to be printed as is when in isolation, but we want it to be bracketed when printing (x + 3) × y. This problem is in reverse: we want to enclose strings unless they appear in a bigger context.

The code generated by the deriving should include a parameter that indicates whether we are serialising a field inside a JSON object or an item inside a JSON list or wether we are serialising a self-standing top-level JSON object.

val foo_to_json: ?toplevel:bool -> t -> json
(* toplevel is true by default for backwards compatibility and for maximum safety *)

and then type t = foo list generates code that calls foo_to_json ~toplevel:false on each element.

[andreypopp]

This library works by encoding/deconding JSON AST rather than raw JSON strings, so it is handled by the underlying JSON codec (either Yojson or in browser JSON implementation).

[Khady]

#26

In the past constructors without a payload were encoded as string