Module json

Description
Data Types
Function Index
Function Details

A JSON library based on: The application/json Media Type for JavaScript Object Notation (JSON) (rfc4627) The JavaScript Object Notation (JSON) Data Interchange Format (rfc7159) JavaScript Object Notation (JSON) Pointer (rfc6901) JSON Reference (draft-pbryan-zyp-json-ref-03) JSON Schema: core definitions and terminology (draft-zyp-json-schema-04) JSON Schema: interactive and non interactive validation (draft-fge-json-schema-validation-00).

Authors: Jan Henry Nystrom (JanHenryNystrom@gmail.com).

Description

JSON is represented as follows:

text : value rfc4627_text : object | array (rfc4627 compability mode) pointer : [integer | string | '-'] schema : object

object : {[{string, value}*]} | map() (maps option enabled) array : [value*] string : atom() | <<octet*>> number : integer() | float() true : atom(true) false : atom(false) null : atom(null)

Strings can be represented by atoms when generating JSON, but will not not be generated when converting JSON to erlang. It can be specified what encoding is used for the strings with UTF-8 being the default. All atoms are assumed to be in UTF-8 and can not be specified.

The encoding of a JSON text is determined and can be specified when converting from Erlang terms with the deafult being UTF-8.

When converting Erlang terms to JSON iolists are generated but it can generate a binary if so instructed.

Objects can be represented directly as maps but that does not allow for duplicate keys so a safe option is provided for decoding. This will change in later realeases where the two object formats will be separated and the slightly more complex maps one will be safe.

When encoding pointers a pointer flag must be given since they cannot be automatically recognised. Pointer evaluation deviates from standard in objects with duplicate keys, they are not checked, this will be provided in coming releases as a strict flag.

When validating a JSON the flags to the validation has to be the same has to be the same as used when decoding either the JSON or schema. When a JSON should be decoded by the validation that has to be indicated by the decode flag.

Only one URI resolver is provided for now and that is against jhn_stdlib's priv dir, is another is provided and validation of schemas is used it has to be abe to resolve http://json-schema.org/draft-04/schema#.

UTF formats are defined in Unicode 5.0 (ISBN 0-321-48091-0).

Data Types

encoding()

encoding() = utf8 | {utf16, little | big} | {utf32, little | big}

json()

json() = json_value() | json_rfc4627_text()

json_array()

json_array() = [json_value()]

json_object()

json_object() = {[{json_string(), json_value()}]} | map()

json_rfc4627_text()

json_rfc4627_text() = json_object() | json_array()

json_string()

json_string() = atom() | string()

json_value()

opt()

opt() = {atom_strings, boolean()} | atom_keys | {atom_keys, boolean()} | existing_atom_keys | {existing_atom_keys, boolean()} | bom | binary | iolist | decode | encode | {plain_string, encoding()} | {encoding, encoding()}

pointer()

pointer() = [binary() | atom() | '-' | pos_integer()]

resolver()

resolver() = fun((uri:uri(), plist:plist() | map()) -> json())

Function Index

decode/1	Decodes the binary into a structured Erlang term.
decode/2	Decodes the binary into a structured Erlang.
encode/1	Encodes the structured Erlang term as an iolist.
encode/2	Encodes the structured Erlang term as an iolist or binary.
eval/2	Selects and decodes a Fragment of a JSON document based on the Pointer.
eval/3	Selects and optionally decodes a Fragment of a JSON document based on the Pointer.
resolve_local_file/2
validate/1	Validates a JSONSchema document based on the json-schema schema.
validate/2	Validates a JSON document based on the Schema.
validate/3	Validates a JSON document, and optionally decodes, based on the Schema.

Function Details

decode/1

decode(Binary::binary()) -> json()

Decodes the binary into a structured Erlang term. Equivalent of decode(JSON, []) -> Term.

decode/2

decode(Binary::binary(), State::[opt()] | #state{pointer = boolean(), maps = boolean() | safe, rfc4627 = boolean(), encoding = encoding(), plain_string = encoding(), atom_strings = boolean(), atom_keys = boolean(), existing_atom_keys = boolean(), bom = boolean(), return_type = iolist | binary, decode = boolean(), encode = boolean(), resolver = {resolver(), plist:plist() | map()}, step = 1 | 2 | 4, pos = integer(), top = json(), top_uri = uri:uri(), scope = uri:uri(), schema = json(), props_validated = boolean()}) -> json()

Decodes the binary into a structured Erlang. Decode will give an exception if the binary is not well formed JSON. Options are: rfc4627 -> compability rfc4627 mode maps -> shorthand for {maps, true} {maps, safe} -> maps are used as representation for objects with unique items {maps, Bool} -> if true maps are used as representation for objects, since this causes potential compatibility issues it is recomended only in combination with schema validation where the schema requires unique items, default false. bom -> the binary to decode has a UTF byte order mark {plain_string, Format} -> what format the strings are encoded in atom_keys -> shorthand for {atom_keys, true} {atom_keys, Bool} -> if true all object keys are converted to atoms, default is false. existing_atom_keys -> shorthand for {existing_atom_keys, true} {existing_atom_keys, Bool} -> if true all object keys are converted to atoms, decoding fails if the atom does not already exist, default is false.

encode/1

encode(Term::json()) -> iolist()

Encodes the structured Erlang term as an iolist. Equivalent of encode(Term, []) -> JSON.

encode/2

encode(Term::json() | pointer(), State::[opt()] | #state{pointer = boolean(), maps = boolean() | safe, rfc4627 = boolean(), encoding = encoding(), plain_string = encoding(), atom_strings = boolean(), atom_keys = boolean(), existing_atom_keys = boolean(), bom = boolean(), return_type = iolist | binary, decode = boolean(), encode = boolean(), resolver = {resolver(), plist:plist() | map()}, step = 1 | 2 | 4, pos = integer(), top = json(), top_uri = uri:uri(), scope = uri:uri(), schema = json(), props_validated = boolean()}) -> iolist() | binary()

Encodes the structured Erlang term as an iolist or binary. Encode will give an exception if the erlang term is not well formed. Options are: pointer -> the term represents a pointer rfc4627 -> compability rfc4627 mode maps -> shorthand for {maps, true} {maps, Bool} -> if true maps is a valid representation for objects, default false. binary -> a binary is returned iolist -> an iolist is returned (default) bom -> a UTF byte order mark is added at the head of the encoding {atom_strings, Bool} -> determines if atoms for strings are allowed {plain_string, Format} -> what format the strings are encoded in {encoding, Encoding} -> what encoding is used for the resulting JSON

eval/2

eval(Pointer::binary(), JSON::binary()) -> json() | binary() | {error, term()}

Selects and decodes a Fragment of a JSON document based on the Pointer. Equivalent of select(JSONPointer, JSON, []) -> Term.

eval/3

eval(Pointer::pointer() | binary(), JSON::json() | binary(), State::[opt()]) -> json() | binary() | {error, term()}

Selects and optionally decodes a Fragment of a JSON document based on the Pointer. Select will give an exception if the binary is not well formed JSON, the pointer not well formed JSON Pointer. Options are: decode -> the JSON selected(value) is decoded bom -> the binary to decode has a UTF byte order mark Options passed to decoding if enabled or the JSON decoded: maps {plain_string, Format} {atom_keys, Bool} {existing_atom_keys, Bool}

resolve_local_file/2

resolve_local_file(Uri, Conf) -> any()

validate/1

validate(Schema::json() | binary()) -> {true, json()} | false

Validates a JSONSchema document based on the json-schema schema.

validate/2

validate(Schema::json() | binary(), JSON::json()) -> true | false

Validates a JSON document based on the Schema. Equivalent of validate(JSONSchema, JSON, [])

validate/3

validate(Schema::json() | binary(), JSON::json() | binary(), State::[opt()]) -> true | {true, json()} | false

Validates a JSON document, and optionally decodes, based on the Schema

If either the schema or the json is already decode they have to be decoded with the same flags and thos provided to the validation.

Options are: decode -> the JSON validated is decoded bom -> the binary to decode has a UTF byte order mark {resolver, Fun, Conf} -> a fun that will used to resolve non local refs Options passed to decoding if enabled or the JSON decoded: maps {plain_string, Format} {atom_keys, Bool} {existing_atom_keys, Bool}

Generated by EDoc