Qore JSON Module  1.8
Qore JSON Module

Introduction

The json module allows for easy serialization and deserialization between JSON strings and Qore data structures. The module also provides functions for JSON-RPC support as well as a JsonRpcClient class for easier integration with JavaScript clients.

Overview of the functionality provided by this module:

This module is released under a choice of two licenses:

  • LGPL 2.1
  • MIT (see COPYING.MIT in the source distribution for more information)

The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the Qore library was initialized).

To use the module in a Qore script, use the %requires directive as follows:

%requires json

Also included with the binary json module:

Note
JSON functionality was included in the main Qore shared library until version 0.8.1, at which time the code was removed to make this module.

Automatic JSON Serialization and Deserialization

JSON Serialization

Qore Type JSON-RPC Type Description
string string direct conversion to UTF-8 string
int number direct conversion
float number direct conversion
bool boolean direct conversion
date string date/time values are serialized to strings like: "2010-12-22 16:35:36.372996 Wed +01:00 (CET)"; intervals are serialized to ISO-8601 duration strings (ex: "PT2M1S")
binary string binary values are serialized as base64 encoded strings
list array direct conversion
hash struct direct conversion
NOTHING or NULL null direct conversion
all others n/a All other types will cause an JSON-RPC-SERIALIZATION-ERROR to be raised.

JSON Deserialization

JSON-RPC Type Qore Type Description
string string direct conversion
number int or float if the JSON number is an integer, it is converted as an int, otherwise as a float
boolean bool direct conversion
array list direct conversion
struct hash direct conversion
null NOTHING direct conversion

This following functions provide automatic JSON serialization and deserialization:

Functions For JSON Serialization and Deserialization

Function Name Description
make_json() Serializes qore data into a JSON string with optional verbose whitespace formatting for easier human readability
parse_json() Parses a JSON string and returns the corresponding Qore data structure

Deprecated JSON Functions

Deprecated Function Name New Function Name
makeFormattedJSONString() make_json()
makeJSONString() make_json()
parseJSON() parse_json()

JSON-RPC

JSON-RPC is a lightweight but powerful JSON over HTTP web service protocol. The json module includes builtin support for several versions of the JSON-RPC protocol; the default protocol version used is "2.0" unless explicitly changed in the JsonRpcClient::constructor().

Classes Providing JSON-RPC Functionality

Class Description
JsonRpcClient For communicating with JSON-RPC servers

Functions Providing JSON-RPC Functionality

Function Name Description
make_jsonrpc_error() a generic JSON-RPC error response string from the parameters passed with optional verbose whitespace formatting for easier human readability
make_jsonrpc_request() Creates a JSON-RPC request string from the parameters passed with optional verbose whitespace formatting for easier human readability
make_jsonrpc_response() Creates a JSON-RPC response string from the parameters passed with optional verbose whitespace formatting for easier human readability

Deprecated JSON-RPC Functions

Deprecated Function Name New Function Name
makeFormattedJSONRPC11ErrorString() support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7
makeFormattedJSONRPCErrorString() make_jsonrpc_error()
makeFormattedJSONRPCRequestString() make_jsonrpc_request()
makeFormattedJSONRPCResponseString() make_jsonrpc_response()
makeJSONRPC11ErrorString() support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7
makeJSONRPCErrorString() make_jsonrpc_error()
makeJSONRPCRequestString() make_jsonrpc_request()
makeJSONRPCResponseString() make_jsonrpc_response()
make_jsonrpc11_error() support for the non-published JSON-RPC 1.1 protocol was deprecated in json 1.7

Function and Method Tags

NOOP

Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s). When variants with this flag are resolved at parse time, a "call-with-type-errors" warning is raised (assuming this warning is enabled), unless PO_REQUIRE_TYPES or PO_STRICT_ARGS is set. If PO_REQUIRE_TYPES or PO_STRICT_ARGS is set, then these variants are inaccessible at parse time; resolving to a variant with this flag set at parse time causes an exception to be thrown.

These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

This tag is equal to RUNTIME_NOOP, except no runtime effect is caused by resolving a function or method tagged with NOOP at runtime; this tag only affects parse time resolution.

RUNTIME_NOOP

Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s). When variants with this flag are resolved at parse time, a "call-with-type-errors" warning is raised (assuming this warning is enabled), unless PO_REQUIRE_TYPES or PO_STRICT_ARGS is set. If PO_REQUIRE_TYPES or PO_STRICT_ARGS is set, then these variants are inaccessible; resolving to a variant with this flag set at parse time or run time causes an exception to be thrown.

These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

This tag is equal to NOOP, except that RUNTIME_NOOP is also enforced at runtime.

RET_VALUE_ONLY

This flag indicates that the function or method has no side effects; it only returns a value, for example.

This tag is identical to CONSTANT except that functions or methods tagged with RET_VALUE_ONLY could throw exceptions.

CONSTANT

This flag indicates that the function or method has no side effects and does not throw any exceptions.

This tag is identical to RET_VALUE_ONLY except that functions or methods tagged with CONSTANT do not throw exceptions.

DEPRECATED

Code with this flag is deprecated and may be removed in a future version of this module; if a variant with this flag is resolved at parse time, a "deprecated" warning is raised (assuming this warning is enabled).

Release Notes

Version 1.8

  • updated the JsonRpcConnection module to support the updated abstract connection API (issue 2628)
  • added support for serializing intervals to strings that can be manually converted to the original value (issue 3135)

Version 1.7

  • deprecated support for the non-published JSON-RPC 1.1 protocol
  • added support for JSON-RPC 2.0
  • added the JsonRpcConnection user module
  • improved argument error messages with RPC calls in the JsonRpcHandler module (issue 2573)
  • fixed date serialization to use ISO-8601 format (instead of near-ISO-8601 format: issue 2655)

Version 1.6

Version 1.5

  • serialize binary values as base64-encoded strings
  • user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore
  • serialize nan, +/-inf as null according to the JSON spec
  • added detection for invalid JSON-RPC calls and added a more user-friendly error message in the JsonRpcHandler module
  • new functions added conforming to Qore's function naming convention, old camel-case functions deprecated
  • JSON tests ported to QUnit
  • Qore 0.8.12 required as a minimum to build
  • JSON output is more compact; less extraneous whitespace is used

Version 1.4

  • date/time values are always serialized with microseconds and in the local time zone for consistency's sake
  • fixed a crashing bug in the JSON control-character encoding algorithm
  • updated the JsonRpcHandler module for enhanced logging
  • source released under the MIT license as well as LGPL 2.1

Version 1.3

  • always include charset=utf-8 in the Content-Type in JsonRpcClient; JSON messages are always serialized with UTF-8 encoding

Version 1.2

  • fixed serialization/deserialization/escaping regarding control characters

Version 1.1

  • added support for the new arbitrary-precision numeric type introduced in qore 0.8.6
  • serialize control characters with escape codes to be compatible with common Javascript JSON libraries (also corresponding deserialization support)

Version 1.0

  • Initial release of the json module
  • Requires qore 0.8.1+ to build and run