Make.Data_encodingtype json = [ | `O of (string * json) list| `Bool of bool| `Float of float| `A of json list| `Null| `String of string ]In memory JSON data
type 'a encoding = 'a tval classify : 'a encoding -> [ `Fixed of int | `Dynamic | `Variable ]val null : unit encodingSpecial value null in JSON, nothing in binary.
val empty : unit encodingEmpty object (not included in binary, encoded as empty object in JSON).
val unit : unit encodingUnit value, omitted in binary. Serialized as an empty object in JSON, accepts any object when deserializing.
val constant : string -> unit encodingConstant string (data is not included in the binary data).
All encodings are big-endians.
A note on 31-bit integers. The internal representation of integers in OCaml reserves one bit for GC tagging. The remaining bits encode a signed integer. For compatibility with 32-bit machine, we restrict these native integers to the 31-bit range.
val int8 : int encodingSigned 8 bit integer (data is encoded as a byte in binary and an integer in JSON).
val uint8 : int encodingUnsigned 8 bit integer (data is encoded as a byte in binary and an integer in JSON).
val int16 : int encodingSigned 16 bit integer (data is encoded as a short in binary and an integer in JSON).
val uint16 : int encodingUnsigned 16 bit integer (data is encoded as a short in binary and an integer in JSON).
val int31 : int encodingSigned 31 bit integer, which corresponds to type int on 32-bit OCaml systems (data is encoded as a 32 bit int in binary and an integer in JSON).
val int32 : int32 encodingSigned 32 bit integer (data is encoded as a 32-bit int in binary and an integer in JSON).
val int64 : int64 encodingSigned 64 bit integer (data is encoded as a 64-bit int in binary and a decimal string in JSON).
val ranged_int : int -> int -> int encodingInteger with bounds in a given range. Both bounds are inclusive.
Big number In JSON, data is encoded as a decimal string. In binary, data is encoded as a variable length sequence of bytes, with a running unary size bit: the most significant bit of each byte tells is this is the last byte in the sequence (0) or if there is more to read (1). The second most significant bit of the first byte is reserved for the sign (positive if zero). Binary_size and sign bits ignored, data is then the binary representation of the absolute value of the number in little-endian order.
val bool : bool encodingEncoding of a boolean (data is encoded as a byte in binary and a boolean in JSON).
val string : string encodingEncoding of a string
Encoding of arbitrary bytes (encoded via hex in JSON and directly as a sequence byte in binary).
Combinator to make an optional value (represented as a 1-byte tag followed by the data (or nothing) in binary and either the raw value or a null in JSON).
Note that the JSON representation is only weakly discriminating. Specifically, the value Some None is represented as the raw value None and so the two are indistinguishable. For this reason, this combinator does not support nesting, nor does it support use within a recursive (mu) encoding.
val result : 'a encoding -> 'b encoding -> ('a, 'b) Pervasives.result encodingCombinator to make a result value represented as a 1-byte tag followed by the data of either type in binary, and either unwrapped value in JSON (the caller must ensure that both encodings do not collide).
Array combinator.
List combinator.
val conv :
('a -> 'b) ->
('b -> 'a) ->
?schema:json_schema ->
'b encoding ->
'a encodingval conv_with_guard :
('a -> 'b) ->
('b -> ('a, string) Pervasives.result) ->
?schema:json_schema ->
'b encoding ->
'a encodingconv_with_guard is similar to conv but the function that takes in the value from the outside (untrusted) world has a chance to fail.
Specifically, if the function returns Error msg then the decoding is interrupted with an error carrying the message msg. If the function returns Ok _ then the decoding proceeds normally.
val with_decoding_guard :
('a -> (unit, string) Pervasives.result) ->
'a encoding ->
'a encodingwith_decoding_guard g e is similar to e but decoding fails if g returns Error _ on the decoded value.
Association list. An object in JSON, a list of pairs in binary.
An enriched encoding to represent a component in a structured type, augmenting the encoding with a name and whether it is a required or optional. Fields are used to encode OCaml tuples as objects in JSON, and as sequences in binary, using combinator obj1 and the like.
Optional field. Omitted entirely in JSON encoding if None. Omitted in binary if the only optional field in a `Variable encoding, otherwise a 1-byte prefix (`0` or `255`) tells if the field is present or not.
Optional field of variable length. Only one can be present in a given object.
Required field with a default value. If the default value is passed, the field is omitted in JSON. The value is always serialized in binary.
These are serialized to binary by converting each internal object to binary and placing them in the order of the original object. These are serialized to JSON as a JSON object with the field names. An object might only contains one 'variable' field, typically the last one. If the encoding of more than one field are 'variable', the first ones should be wrapped with dynamic_size.
Create a larger object from the encodings of two smaller ones.
These are serialized to binary by converting each internal object to binary and placing them in the order of the original object. These are serialized to JSON as JSON arrays/lists. Like objects, a tuple might only contains one 'variable' field, typically the last one. If the encoding of more than one field are 'variable', the first ones should be wrapped with dynamic_size.
Create a large tuple encoding from two smaller ones.
A partial encoding to represent a case in a variant type. Hides the (existentially bound) type of the parameter to the specific case, providing its encoder, and converter functions to and from the union type.
type 'a matching_function = 'a -> match_resultA sum descriptor can be optimized by providing a specific matching_function which efficiently determines in which case some value of type 'a falls.
Note that in general you should use a total function (i.e., one defined over the whole of the 'a type) for the matching_function. However, in the case where you have a good reason to use a partial function, you should raise No_case_matched in the dead branches. Reasons why you may want to do so include:
'a is an open variant and you will complete the matching function later, and'a is not fully inhabited.val matched : ?tag_size:tag_size -> int -> 'a encoding -> 'a -> match_resultval case :
title:string ->
?description:string ->
case_tag ->
'a encoding ->
('t -> 'a option) ->
('a -> 't) ->
't caseEncodes a variant constructor. Takes the encoding for the specific parameters, a recognizer function that will extract the parameters in case the expected case of the variant is being serialized, and a constructor function for deserialization.
The tag must be less than the tag size of the union in which you use the case. An optional tag gives a name to a case and should be used to maintain compatibility.
An optional name for the case can be provided, which is used in the binary documentation.
val matching :
?tag_size:tag_size ->
't matching_function ->
't case list ->
't encodingCreate a single encoding from a series of cases.
In JSON, all cases are tried one after the other using the case list. The caller is responsible for avoiding collisions. If there are collisions (i.e., if multiple cases produce the same JSON output) then the encoding and decoding processes might not be inverse of each other. In other words, destruct e (construct e v) may not be equal to v.
In binary, a prefix tag is added to discriminate quickly between cases. The default is `Uint8 and you must use a `Uint16 if you are going to have more than 256 cases.
The matching function is used during binary encoding of a value v to efficiently determine which of the cases corresponds to v. The case list is used during decoding to reconstruct a value based on the encoded tag. (Decoding is optimised internally: tag look-up has a constant cost.)
The caller is responsible for ensuring that the matching_function and the case list describe the same encoding. If they describe different encodings, then the decoding and encoding processes will not be inverses of each others. In other words, of_bytes e (to_bytes e v) will not be equal to v.
If you do not wish to be responsible for this, you can use the unoptimised union that uses a case list only (see below). Beware that in union the complexity of the encoding is linear in the number of cases.
Following: a basic example use. Note that the matching_function uses the same tags, payload conversions, and payload encoding as the case list.
type t = A of string | B of int * int | C
let encoding_t =
(* Tags and payload encodings for each constructors *)
let a_tag = 0 and a_encoding = string in
let b_tag = 1 and b_encoding = obj2 (req "x" int) (req "y" int) in
let c_tag = 2 and c_encoding = unit in
matching
(* optimised encoding function *)
(function
| A s -> matched a_tag a_encoding s
| B (x, y) -> matched b_tag b_encoding (x, y)
| C -> matched c_tag c_encoding ())
(* decoding case list *)
[
case ~title:"A"
(Tag a_tag)
a_encoding
(function A s -> Some s | _ -> None) (fun s -> A s);
case ~title:"B"
(Tag b_tag)
b_encoding
(function B (x, y) -> Some (x, y) | _ -> None) (fun (x, y) -> B (x, y));
case ~title:"C"
(Tag c_tag)
c_encoding
(function C -> Some () | _ -> None) (fun () -> C);
]Same as matching except that the matching function is a linear traversal of the cases.
val string_enum : (string * 'a) list -> 'a encodingEncode enumeration via association list
module Fixed : sig ... endCreate encodings that produce data of a fixed length when binary encoded. See the preamble for an explanation.
module Variable : sig ... endCreate encodings that produce data of a variable length when binary encoded. See the preamble for an explanation.
module Bounded : sig ... endMark an encoding as being of dynamic size. Forces the size to be stored alongside content when needed. Typically used to combine two variable encodings in a same objects or tuple, or to use a variable encoding in an array or a list.
check_size size encoding ensures that the binary encoding of a value will not be allowed to exceed size bytes. The reader and the writer fails otherwise. This function do not modify the JSON encoding.
Define different encodings for JSON and binary serialization.
val mu :
string ->
?title:string ->
?description:string ->
('a encoding -> 'a encoding) ->
'a encodingCombinator for recursive encodings.
Notice that the function passed to mu must be pure. Otherwise, the behavior is unspecified.
A stateful recursive encoding can still be put under a delayed combinator to make sure that a new encoding is generated each time it is used. Caching the encoding generation when the state has not changed is then the responsability of the client.
Give a name to an encoding and optionally add documentation to an encoding.
See lazy_encoding below.
Combinator to have a part of the binary encoding lazily deserialized. This is transparent on the JSON side.
val force_decode : 'a lazy_t -> 'a optionForce the decoding (memoized for later calls), and return the value if successful.
val force_bytes : 'a lazy_t -> bytesObtain the bytes without actually deserializing. Will serialize and memoize the result if the value is not the result of a lazy deserialization.
val apply_lazy :
fun_value:('a -> 'b) ->
fun_bytes:(bytes -> 'b) ->
fun_combine:('b -> 'b -> 'b) ->
'a lazy_t ->
'bApply on structure of lazy value, and combine results
module Compact : sig ... endThis module provides specialized encoding combinators that are implemented to reduce the size of the serialization result.
type 'a compact = 'a Compact.tval json_schema : json_schema encodingmodule Json : sig ... endmodule Binary : sig ... end