Module Json_schema
Abstract representation of schemas
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 forupdate
. 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
andMonomorphicArray
type specifiers.
and numeric_specs
=
{
}
Parameters of the
Integer
andNumber
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 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, seesimplify
.
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 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 raiseDuplicate_definition
if this path is already used or any error raised byJson_repr
.path_of_json_pointer with~wildcards:false
. Returns the modified schema and theDef_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
. Seeadd_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
andMonomorphicArray
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
andNumber
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 functorMake
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 functorMake
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
Duplicate_definition of Json_query.path * element * element
A non-
Dummy
definition appeared twice on insertion or merge.
Advanced interface for using a custom JSON representation
module Make : functor (Repr : Json_repr.Repr) -> sig ... end