ocplib-json-typed

Type-aware JSON and JSON schema utilities
Module Json_schema

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.

*)
}

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 : 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