conformist 0.1.0 · OCaml Package

Conformist is a library for creating and validating schemas. It provides run-time types without using any ppx. It can be used to validate incoming data and to translate it to static types for safe usage.

Example

Let's start with an example. We have a static type that represents a user.

type gender = Male | Female | Other

type user = {
  gender : gender;
  email : string;
  birthday : int * int * int;
  nr_of_siblings : int;
  comment : string option;
  wants_premium : bool;
}

In order to create a conformist schema, we need a constructor that takes all the record fields and create a user.

let user gender email birthday nr_of_siblings comment wants_premium
    =
  {
    gender;
    email;
    birthday;
    nr_of_siblings;
    comment;
    wants_premium;
  }

Now we can create a schema.

let gender_decoder = function
  | "male" -> Ok Male
  | "female" -> Ok Female
  | "other" -> Ok Other
  | _ -> Error "Unknown gender provided"

let gender_encoder = function
  | Male -> "male"
  | Female -> "female"
  | Other -> "other"


module C = Conformist

let user_schema =
  C.make
    C.Field.
      [
        C.custom gender_decoder gender_encoder "gender" ~meta:();
        C.string "email";
        C.date "birthday";
        C.int ~default:0 "nr_of_siblings";
        C.optional (C.string "comment");
        C.bool "wants_premium");
      ]
    user

Try to delete/swap lines of that list, to change the constructor or the user type. The code doesn't compile anymore!

user_schema showcases the creation of a custom type and optional types.

This is how you can decode a user given some input:

let user =
  let input =
    [
      ("gender", [ "male" ]);
      ("email", [ "test@example.com" ]);
      ("birthday", [ "2020-12-01" ]);
      ("nr_of_siblings", [ "3" ]);
      ("comment", [ "hello" ]);
      ("wants_premium", [ "true" ]);
    ]
  in
  C.decode Schema.user_schema input

Decoding doesn't validate the data, it just makes sure that the types are correct and translates strings to the correct static types.

We can validate data based on our validator per field.

let validation_errors =
  let input =
    [
      ("gender", [ "male" ]);
      ("email", [ "test@example.com" ]);
      ("birthday", [ "2020-12-01" ]);
      ("nr_of_siblings", [ "3" ]);
      ("comment", [ "hello" ]);
      ("wants_premium", [ "true" ]);
    ]
  in
  C.validate Schema.user_schema input

Note that if decoding of a field fails, validation fails as well since before a field is validated it gets decoded.

Fields

Every member of the list in the example is a field. Use the provided fold_left to traverse the list of fiels. Helper functions are provided that operate on fields.

module Field : sig ... end

type 'a decoder = string -> ('a, string) Stdlib.result

A 'a decoder tries to turn a string into a value of type 'a. It returns a descriptive errors message upon failure.

type 'a encoder = 'a -> string

A 'a encoder encodes a value of type 'a into a string.

type 'a validator = 'a -> string option

A 'a validator takes something of type 'a and returns an error string if validation fails, None if everything is ok

val custom : 
  'a decoder ->
  'a encoder ->
  ?default:'a ->
  ?type_:string ->
  ?meta:'b ->
  ?validator:'a validator ->
  string ->
  ('b, 'a) Field.t

Use custom decoder encoder ?default ?type_ ?meta ?validator field_name to create a field with a custom type that is not supported out-of-the box. Provide a custom decoder with a descriptive error message so conformist knows how to turn a string into your custom value.

A string representation of the static type_ can also be provided, by default the field_name is taken.