package data-encoding

  1. Overview
  2. Docs
type json = [
  1. | `O of (string * json) list
  2. | `Bool of bool
  3. | `Float of float
  4. | `A of json list
  5. | `Null
  6. | `String of string

In memory JSON data, compatible with Ezjsonm.

type t = json
type schema = Json_schema.schema
val encoding : json Encoding.t

Encodes raw JSON data (BSON is used for binary).

val schema_encoding : schema Encoding.t

Encodes a JSON schema (BSON encoded for binary).

val convert : 'a Encoding.t -> 'a Json_encoding.encoding

Create a Json_encoding.encoding from an encoding.

val schema : ?definitions_path:string -> 'a Encoding.t -> schema

Generate a schema from an encoding.

val construct : ?include_default_fields:[ `Always | `Auto | `Never ] -> 't Encoding.t -> 't -> json

Construct a JSON object from an encoding.

type jsonm_lexeme = [
  1. | `Null
  2. | `Bool of bool
  3. | `String of string
  4. | `Float of float
  5. | `Name of string
  6. | `As
  7. | `Ae
  8. | `Os
  9. | `Oe
val construct_seq : 't Encoding.t -> 't -> jsonm_lexeme Stdlib.Seq.t

construct_seq enc t is a representation of t as a sequence of json lexeme (jsonm_lexeme Seq.t). This sequence is lazy: lexemes are computed on-demand.

val string_seq_of_jsonm_lexeme_seq : newline:bool -> chunk_size_hint:int -> jsonm_lexeme Stdlib.Seq.t -> string Stdlib.Seq.t

string_seq_of_jsonm_lexeme_seq ~newline ~chunk_size_hint s is a sequence of strings, the concatenation of which is a valid textual representation of the json value represented by s. Each string chunk is roughly chunk_size_hint long (except the last one that may be shorter).

With the newline parameter set to true, a single newline character is appended to the textual representation.

Forcing one element of the resulting string sequence forces multiple elements of the underlying lexeme sequence. Once enough lexemes have been forced that roughly chunk_size_hint characters are needed to represent them, the representation is returned and the rest of the sequence is held lazily.

Note that most chunks split at a lexeme boundary. This may not be true for string literals or float literals, the representation of which may be spread across multiple chunks.

val small_string_seq_of_jsonm_lexeme_seq : newline:bool -> jsonm_lexeme Stdlib.Seq.t -> string Stdlib.Seq.t
val blit_instructions_seq_of_jsonm_lexeme_seq : newline:bool -> buffer:bytes -> jsonm_lexeme Stdlib.Seq.t -> (Stdlib.Bytes.t * int * int) Stdlib.Seq.t

blit_instructions_seq_of_jsonm_lexeme_seq ~newline ~buffer json is a sequence of (buff, offset, length) such that the concatenation of the sub-strings thus designated represents the json value in text form.

The intended use is to blit each of the substring onto whatever output the consumer decides. In most cases, the Sequence's buff is physically equal to buffer. This is not always true and one cannot rely on that fact. E.g., when the json includes a long string literal, the function might instruct the consumer to blit from that literal directly.

This function performs few allocations, especially of fresh strings.

Note that once the next element of the sequence is forced, the blit instructions become invalid: the content of buff may have been rewritten by the side effect of forcing the next element.

  • raises [Invalid_argument]

    if Bytes.length buffer is less than 32.

val destruct : ?bson_relaxation:bool -> 't Encoding.t -> json -> 't

Destruct a JSON object into a value. Fail with an exception if the JSON object and encoding do not match.

  • parameter [bson_relaxation]

    (default to false) works around a limitation of the BSON format. Specifically, in BSON, top-level arrays are represented as number-indexed objects. When bson_relaxation is true, then the destructor attempts to automatically translate the indistinguishable values as guided by the encoding.

JSON Error.

type path = path_item list
and path_item = [
  1. | `Field of string

    A field in an object.

  2. | `Index of int

    An index in an array.

  3. | `Star

    Any / every field or index.

  4. | `Next

    The next element after an array.


A set of accessors that point to a location in a JSON object.

exception Cannot_destruct of path * exn

Exception raised by destructors, with the location in the original JSON structure and the specific error.

exception Unexpected of string * string

Unexpected kind of data encountered, with the expectation.

exception No_case_matched of exn list

Some union couldn't be destructed, with the reasons for each case.

exception Bad_array_size of int * int

Array of unexpected size encountered, with the expectation.

exception Missing_field of string

Missing field in an object.

exception Unexpected_field of string

Supernumerary field in an object.

val print_error : ?print_unknown:(Stdlib.Format.formatter -> exn -> unit) -> Stdlib.Format.formatter -> exn -> unit
val cannot_destruct : ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a

Helpers for writing encoders.

val wrap_error : ('a -> 'b) -> 'a -> 'b
val from_string : string -> (json, string) Stdlib.result

Read a JSON document from a string.

val to_string : ?newline:bool -> ?minify:bool -> json -> string

Write a JSON document to a string. This goes via an intermediate buffer and so may be slow on large documents.

val pp : Stdlib.Format.formatter -> json -> unit

Innovation. Community. Security.