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.

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 : Stdlib.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:(Stdlib.Format.formatter -> exn -> unit) -> Stdlib.Format.formatter -> exn -> unit

Produces a human readable version of an error.

Advanced interface for using a custom JSON representation

module Make : functor (Repr : Json_repr.Repr) -> sig ... end