package tezos-openapi

  1. Overview
  2. Docs

Module Tezos_openapi.JsonSource

Helpers to read JSON values.

Contains functions to parse JSON values, show them for debugging, and extract information from them.

Functions which extract information are rather strict: they don't try to be smart and automatically convert. For instance, as_record makes sure that all fields are taken into account. This is suited to write a tool that must be updated when the format of JSON values being manipulated changes. In our case, if the JSON schemas we read start to get more fields, we want to know; otherwise the resulting OpenAPI specification could be inaccurate.

include module type of struct include JSON end
Sourcetype error = JSON.error

Errors that can happen when parsing or reading JSON.

Sourceval show_error : error -> string

Convert a JSON parse error to a string.

Sourceexception Error of error

Exception that can happen when parsing or reading JSON.

JSON unannotated ASTs.

Sourcetype t = JSON.t

JSON ASTs annotated with their origin.

The origin is a string you give to annotate or parse, such as "RPC response". It denotes where the value comes from. It is used in error messages (see the comment in the Decoding section).

Sourceval error : t -> ('a, unit, string, 'b) format4 -> 'a

Raise Error.

The JSON.t argument is used to annotate the error message with the location of the JSON value.

Sourceval annotate : origin:string -> u -> t

Annotate a JSON AST with its origin.

Sourceval unannotate : t -> u

Remove annotation from an annotated JSON AST.

Encoding

Sourceval encode : t -> string

Encode a JSON annotated AST into a string.

Sourceval encode_u : u -> string

Encode a JSON unannotated AST into a string.

Sourceval encode_to_file : string -> t -> unit

Encode a JSON annotated AST into a file.

Sourceval encode_to_file_u : string -> u -> unit

Encode a JSON unannotated AST into a file.

Decoding

Sourceval parse_file : string -> t

Parse a JSON file.

  • raises Error

    if the input is invalid JSON.

Sourceval parse : origin:string -> string -> t

Parse a JSON string.

  • raises Error

    if the input is invalid JSON.

Sourceval parse_opt : origin:string -> string -> t option

Same as parse, but return None instead of raising Error.

The general pattern for the accessors below is that only as_x functions can fail. Getters get and geti return `Null instead of failing. This allows to chain them and only test for errors at the end with as_x, either by raising Error or by returning None (with the as_x_opt variant).

Internally, the actual error which is printed is the correct one. For instance, with json |-> "x" |> as_int, if json is not an object, the call to as_int causes the test to fail with "<origin>: not an object" where <origin> is the ~origin you gave to parse. If json is an object but "x" does not exist, as_int causes the test to fail with "<origin>: missing field: x". If "x" exists but is not an integer, as_int causes the test to fail with "<origin> at .x: expected an integer".

Sourceval get : string -> t -> t

Get the value for a field of a JSON object.

If the JSON value is not an object, or if the field does not exist, return `Null.

Sourceval (|->) : t -> string -> t

Same as get, with the arguments reversed.

Sourceval geti : int -> t -> t

Get the value for a field of a JSON array.

If the JSON value is not an array, or if the field does not exist, return `Null.

Sourceval (|=>) : t -> int -> t

Same as geti, with the arguments reversed.

Sourceval put : (string * t) -> t -> t

Updates an object with a (key, value) pair.

put (key, value) obj puts value under key in obj. If the key already exists, it is overwritten. Otherwise a new key is added at the end of the object.

  • raises Error

    if obj is not a JSON object.

Sourceval update : string -> (t -> t) -> t -> t

Alters the value of a specific key in a JSON object by applying its value to a function. Returns updated object.

update key f obj is equivalent to put (key, f (get key obj)) obj.

Note: if key is not present in obj, `Null is passed to f instead.

  • raises Error

    if obj is not an object.

Sourceval filter_map_object : t -> (string -> t -> t option) -> t

filter_map_object obj f maps f over each field in obj.

If f key value is None then the key is removed from obj. If f key value is Some value' then the key is overwritten with value'.

  • raises Error

    if obj is not an object.

Sourceval filter_object : t -> (string -> t -> bool) -> t

filter_object obj f filters the bindings in obj.

filter_object obj f removes each binding key, value in obj for which f key value is false.

  • raises Error

    if obj is not an object.

Sourceval merge_objects : t -> t -> t

Non-recursively merges two objects.

merge_objects o1 o2 returns an object containing all fields of o1 and o2. If a key exists in both o1 and o2, then it will be bound to its value in o2.

  • raises Error

    if o1 or o2 is not an object.

Sourceval is_null : t -> bool

Test whether a JSON value is `Null.

Sourceval as_opt : t -> t option

Return None if a JSON value is `Null, Some otherwise.

Example: JSON.(json |> as_opt |> Option.map read_record)

Sourceval as_bool : t -> bool

Get the value from a `Bool node.

  • raises Error

    if the input is not a `Bool.

Sourceval as_bool_opt : t -> bool option

Same as as_bool, but return None instead of raising Error.

Sourceval is_bool : t -> bool

Test whether as_bool would succeed.

Sourceval as_int : t -> int

Get the integer value from a `Float or `String node.

  • raises Error

    if:

    • the input is not a `Float nor a `String;
    • the input is a `Float but is not an integer;
    • the input is a `String but does not denote a valid decimal integer.
Sourceval as_int_opt : t -> int option

Same as as_int, but return None instead of raising Error.

Sourceval is_int : t -> bool

Test whether as_int would succeed.

Sourceval as_int64 : t -> int64

Get the integer value from a `Float or `String node (64-bit version).

  • raises Error

    if:

    • the input is not a `Float nor a `String;
    • the input is a `Float but is not an integer;
    • the input is a `String but does not denote a valid decimal integer.
Sourceval as_int64_opt : t -> int64 option

Same as as_int64, but return None instead of raising Error.

Sourceval is_int64 : t -> bool

Test whether as_int64 would succeed.

Sourceval as_int32 : t -> int32

Get the integer value from a `Float or `String node (32-bit version).

  • raises Error

    if:

    • the input is not a `Float nor a `String;
    • the input is a `Float but is not an integer;
    • the input is a `String but does not denote a valid decimal integer.
Sourceval as_int32_opt : t -> int32 option

Same as as_int32, but return None instead of raising Error.

Sourceval is_int32 : t -> bool

Test whether as_int32 would succeed.

Sourceval as_float : t -> float

Get the float value from a `Float or `String node.

  • raises Error

    if:

    • the input is not a `Float nor a `String;
    • the input is a `String but does not denote a valid decimal float.
Sourceval as_float_opt : t -> float option

Same as as_float, but return None instead of raising Error.

Sourceval is_float : t -> bool

Test whether as_float would succeed.

Sourceval as_string : t -> string

Get the value from a `String node.

  • raises Error

    if the input is not a `String.

Sourceval as_string_opt : t -> string option

Same as as_string, but return None instead of raising Error.

Sourceval is_string : t -> bool

Test whether as_string would succeed.

Sourceval as_list : t -> t list

Get the list of items from an `Array node.

  • raises Error

    if the input is not an `Array nor `Null. Return the empty list if the input is `Null.

Sourceval as_list_opt : t -> t list option

Same as as_list, but return None instead of raising Error.

Sourceval is_list : t -> bool

Test whether as_list would succeed.

Sourceval as_object : t -> (string * t) list

Get the list of fields from an `Object node.

  • raises Error

    if the input is not an `Object nor `Null. Return the empty list if the input is `Null.

Sourceval as_object_opt : t -> (string * t) list option

Same as as_object, but return None instead of raising Error.

Sourceval is_object : t -> bool

Test whether as_object would succeed.

Sourceval equal_u : u -> u -> bool

Equality for JSON unannotated ASTs.

Objects are equal only when they have the exact same number of fields with the same contents (their order does not matter). Consequently, e.g. {"a": 1} is not equal to {"a": 1, "a": 1}.

Arrays are equal when they contain the same number of pair-wise equal elements.

Sourceval equal : t -> t -> bool

Equality for JSON annotated ASTs.

Annotations are stripped, then the unannotated AST is compared with equal_u.

Sourceval as_variant : t -> string * t
Sourceval as_variant_named : t -> string -> t
Sourceval (|~>) : t -> string -> t
Sourceval as_record : t -> ((string -> t option) -> 'a) -> 'a
Sourceval output : Ezjsonm.value -> unit