json-data-encoding 0.12.1 · OCaml Package

Abstract representation of schemas

type schema

A JSON schema root.

and element = {

title : string option;
(*
An optional short description.
*)
description : string option;
(*
An optional long description.
*)
default : Json_repr.any option;
(*
A default constant to be substituted in case of a missing value.
*)
enum : Json_repr.any list option;
(*
A valid value must equal one of these constants.
*)
kind : element_kind;
(*
The type-specific part.
*)
format : string option;
(*
predefined formats such as date-time, email, ipv4, ipv6, uri.
*)
id : string option;
(*
An optional ID.
*)

}

A node in the schema, embeds all type-agnostic specs.

and element_kind =

| Object of object_specs
(*
The type of an object.
*)
| Array of element list * array_specs
(*
An fixed-length array with the types of its elements (a tuple).
*)
| Monomorphic_array of element * array_specs
(*
A variable-length array with the type of its children.
*)
| Combine of combinator * element list
(*
A mix of schemas using logical combinators.
*)
| Def_ref of Json_query.path
(*
A ref to an element from its path in the JSON representation.
*)
| Id_ref of string
(*
A ref to an element from its ID.
*)
| Ext_ref of Uri.t
(*
A ref to an external element.
*)
| String of string_specs
(*
A string (with optional characteristics).
*)
| Integer of numeric_specs
(*
An int (with optional characteristics).
*)
| Number of numeric_specs
(*
A float (with optional characteristics).
*)
| Boolean
(*
Any boolean.
*)
| Null
(*
The null value.
*)
| Any
(*
Any JSON value.
*)
| Dummy
(*
For building cyclic definitions, a definition bound to a dummy will be considered absent for add_definition but present for update. The idea is to insert a dummy definition, build a cyclic structure using it for recursion, and finally update the definition with the structure.
*)

The type-specific part of schema nodes.

and combinator =

| Any_of
(*
Logical OR n-ary combinator.
*)
| One_of
(*
Logical XOR n-ary combinator.
*)
| All_of
(*
Logical AND n-ary combinator.
*)
| Not
(*
Logical NOT unary combinator.
*)

Grammar combinators.

and array_specs = {

min_items : int;
(*
The minimum number of elements.
*)
max_items : int option;
(*
The maximum number of elements.
*)
unique_items : bool;
(*
Teels if all elements must be different.
*)
additional_items : element option;
(*
The type of additional items, if allowed.
*)

}

Parameters of the Array and MonomorphicArray type specifiers.

and numeric_specs = {

multiple_of : float option;
(*
An optional divisor of valid values
*)
minimum : (float * [ `Inclusive | `Exclusive ]) option;
(*
The optional lower bound of the numeric range
*)
maximum : (float * [ `Inclusive | `Exclusive ]) option;
(*
The optional upper bound of the numeric range
*)

}

Parameters of the Integer and Number type specifiers.

and object_specs = {

properties : (string * element * bool * Json_repr.any option) list;
(*
The names and types of properties, with a flag to indicate if they are required (true) or optional.
*)
pattern_properties : (string * element) list;
(*
Alternative definition of properties, matching field names using regexps instead of constant strings.
*)
additional_properties : element option;
(*
The type of additional properties, if allowed.
*)
min_properties : int;
(*
The minimum number of properties.
*)
max_properties : int option;
(*
The maximum number of properties.
*)
schema_dependencies : (string * element) list;
(*
Additional schemas the value must verify if a property is present (property, additional schema).
*)
property_dependencies : (string * string list) list;
(*
Additional properties required whenever some property is present (property, additional properties).
*)

}

Parameters of the Object type specifier.

and string_specs = {

pattern : string option;
(*
A regexp the string must conform to.
*)
min_length : int;
(*
The minimum string length.
*)
max_length : int option;
(*
The maximum string length.
*)
str_format : string option;
(*
Special format of the string (cf json schema documentation).
*)

}

Parameters of the String type specifier.

Combinators to build schemas and elements

val element : element_kind -> element

Construct a naked element (all optional properties to None).

val create : element -> schema

Construct a schema from its root, without any definition ; the element is checked not to contain any Def element.

val root : schema -> element

Extract the root element from an existing schema.

val update : element -> schema -> schema

Update a schema from its root, using the definitions from an existing schema ; the element is checked to contain only valid Def elements ; unused definitions are kept, see simplify.

val self : schema

Describes the implemented schema specification as a schema.

val any : schema

A completely generic schema, without any definition.

val combine : combinator -> schema list -> schema

Combines several schemas.

val is_nullable : schema -> bool

Tells is a schema accepts null.

Named definitions

val merge_definitions : (schema * schema) -> schema * schema

Merges the definitions of two schemas if possible and returns the updated schemas, so that their elements can be mixed without introducing dangling references ; if two different definitions are bound to the same path, Duplicate_definition will be raised.

val simplify : schema -> schema

Remove the definitions that are not present in the schema.

val add_definition : 
  ?definitions_path:string ->
  string ->
  element ->
  schema ->
  schema * element

Adds a definition by its path. If the path is absolute (starting with a '/'), it is untouched. Otherwise, it is considered relative to "#/definitions" as recommended by the standard. May raise Duplicate_definition if this path is already used or any error raised by Json_repr.path_of_json_pointer with ~wildcards:false. Returns the modified schema and the Def_ref node that references this definition to be used in the schema.

val find_definition : ?definitions_path:string -> string -> schema -> element

Finds a definition by its path, may raise Not_found. See add_definition for the name format.

val definition_exists : ?definitions_path:string -> string -> schema -> bool

Tells if a path leads to a definition. See add_definition for the name format.

val definition_ref : ?definitions_path:string -> string -> element

Build a reference to a definition. See add_definition for the name format.

Predefined values

val array_specs : array_specs

Default Parameters of the Array and MonomorphicArray type specifiers.

val object_specs : object_specs

Default parameters of the Object type specifier.

val string_specs : string_specs

Default parameters of the String type specifier.

val numeric_specs : numeric_specs

Default parameters of the Integer and Number type specifiers.

JSON Serialization

val to_json : schema -> Json_repr.ezjsonm

Formats a JSON schema as its JSON representation.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

val of_json : ?definitions_path:string -> Json_repr.ezjsonm -> schema

Parse a JSON structure as a JSON schema, if possible. May throw Cannot_parse.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

val pp : Format.formatter -> schema -> unit

Formats a JSON schema in human readable format.

Errors

exception Cannot_parse of Json_query.path * exn

An error happened during parsing. May box one of the following exceptions, among others..

exception Dangling_reference of Uri.t

A reference to a non-existent location was detected.

exception Bad_reference of string

A reference litteral could not be understood.

exception Unexpected of string * string

An unexpected kind of JSON value was encountered.

exception Duplicate_definition of Json_query.path * element * element

A non-Dummy definition appeared twice on insertion or merge.

val print_error : 
  ?print_unknown:(Format.formatter -> exn -> unit) ->
  Format.formatter ->
  exn ->
  unit

Produces a human readable version of an error.

Advanced interface for using a custom JSON representation

module Make (Repr : Json_repr.Repr) : sig ... end

package json-data-encoding