package json-data-encoding

  1. Overview
  2. Docs
package json-data-encoding
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module Json_schemaSource

Abstract representation of schemas

Sourcetype schema

A JSON schema root.

Sourceand 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.

Sourceand 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.

Sourceand 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.

Sourceand 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.

Sourceand 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.

Sourceand 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.

Sourceand 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.

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

Sourceval element : element_kind -> element

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

Sourceval create : element -> schema

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

Sourceval root : schema -> element

Extract the root element from an existing schema.

Sourceval 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.

Sourceval self : schema

Describes the implemented schema specification as a schema.

Sourceval any : schema

A completely generic schema, without any definition.

Sourceval combine : combinator -> schema list -> schema

Combines several schemas.

Sourceval is_nullable : schema -> bool

Tells is a schema accepts null.

Named definitions

Sourceval 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.

Sourceval simplify : schema -> schema

Remove the definitions that are not present in the schema.

Sourceval 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.

Sourceval 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.

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

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

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

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

Predefined values

Sourceval array_specs : array_specs

Default Parameters of the Array and MonomorphicArray type specifiers.

Sourceval object_specs : object_specs

Default parameters of the Object type specifier.

Sourceval string_specs : string_specs

Default parameters of the String type specifier.

Sourceval numeric_specs : numeric_specs

Default parameters of the Integer and Number type specifiers.

JSON Serialization

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.

Sourceval 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.

Formats a JSON schema in human readable format.

Errors

Sourceexception Cannot_parse of Json_query.path * exn

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

Sourceexception Dangling_reference of Uri.t

A reference to a non-existent location was detected.

Sourceexception Bad_reference of string

A reference litteral could not be understood.

Sourceexception Unexpected of string * string

An unexpected kind of JSON value was encountered.

Sourceexception Duplicate_definition of Json_query.path * element * element

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

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

Produces a human readable version of an error.

Advanced interface for using a custom JSON representation

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