json-data-encoding
  1. Overview
  2. Docs

Abstract representation of JSON schemas as of version http://json-schema.org/draft-04/schema#.

Abstract representation of schemas

type schema

A JSON schema root.

and element = {
  1. title : string option;
    (*

    An optional short description.

    *)
  2. description : string option;
    (*

    An optional long description.

    *)
  3. default : Json_repr.any option;
    (*

    A default constant to be substituted in case of a missing value.

    *)
  4. enum : Json_repr.any list option;
    (*

    A valid value must equal one of these constants.

    *)
  5. kind : element_kind;
    (*

    The type-specific part.

    *)
  6. format : string option;
    (*

    predefined formats such as date-time, email, ipv4, ipv6, uri.

    *)
  7. id : string option;
    (*

    An optional ID.

    *)
}

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

and element_kind =
  1. | Object of object_specs
    (*

    The type of an object.

    *)
  2. | Array of element list * array_specs
    (*

    An fixed-length array with the types of its elements (a tuple).

    *)
  3. | Monomorphic_array of element * array_specs
    (*

    A variable-length array with the type of its children.

    *)
  4. | Combine of combinator * element list
    (*

    A mix of schemas using logical combinators.

    *)
  5. | Def_ref of Json_query.path
    (*

    A ref to an element from its path in the JSON representation.

    *)
  6. | Id_ref of string
    (*

    A ref to an element from its ID.

    *)
  7. | Ext_ref of Uri.t
    (*

    A ref to an external element.

    *)
  8. | String of string_specs
    (*

    A string (with optional characteristics).

    *)
  9. | Integer of numeric_specs
    (*

    An int (with optional characteristics).

    *)
  10. | Number of numeric_specs
    (*

    A float (with optional characteristics).

    *)
  11. | Boolean
    (*

    Any boolean.

    *)
  12. | Null
    (*

    The null value.

    *)
  13. | Any
    (*

    Any JSON value.

    *)
  14. | 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 =
  1. | Any_of
    (*

    Logical OR n-ary combinator.

    *)
  2. | One_of
    (*

    Logical XOR n-ary combinator.

    *)
  3. | All_of
    (*

    Logical AND n-ary combinator.

    *)
  4. | Not
    (*

    Logical NOT unary combinator.

    *)

Grammar combinators.

and array_specs = {
  1. min_items : int;
    (*

    The minimum number of elements.

    *)
  2. max_items : int option;
    (*

    The maximum number of elements.

    *)
  3. unique_items : bool;
    (*

    Teels if all elements must be different.

    *)
  4. additional_items : element option;
    (*

    The type of additional items, if allowed.

    *)
}

Parameters of the Array and MonomorphicArray type specifiers.

and numeric_specs = {
  1. multiple_of : float option;
    (*

    An optional divisor of valid values

    *)
  2. minimum : (float * [ `Inclusive | `Exclusive ]) option;
    (*

    The optional lower bound of the numeric range

    *)
  3. maximum : (float * [ `Inclusive | `Exclusive ]) option;
    (*

    The optional upper bound of the numeric range

    *)
}

Parameters of the Integer and Number type specifiers.

and object_specs = {
  1. 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.

    *)
  2. pattern_properties : (string * element) list;
    (*

    Alternative definition of properties, matching field names using regexps instead of constant strings.

    *)
  3. additional_properties : element option;
    (*

    The type of additional properties, if allowed.

    *)
  4. min_properties : int;
    (*

    The minimum number of properties.

    *)
  5. max_properties : int option;
    (*

    The maximum number of properties.

    *)
  6. schema_dependencies : (string * element) list;
    (*

    Additional schemas the value must verify if a property is present (property, additional schema).

    *)
  7. 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 = {
  1. pattern : string option;
    (*

    A regexp the string must conform to.

    *)
  2. min_length : int;
    (*

    The minimum string length.

    *)
  3. 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