@JsonParse

As input, either TEXT or a VSPECBINBUFFER can be supplied. The content is interpreted as JSON and must be encoded in UTF-8.

If parsing is successful, @JsonParse returns a VSPECHJSON (HJS) handle to the created JSON structure.
The handle can subsequently be used, for example, with @JsonGet, @JsonAdd, or @JsonSerialize and must be released with @JsonRelease after use.

By default, the standard rules of the JSON parser are used.
Additional parser options can be specified using the optional numeric parameter FN OPTIONS. The value is passed directly to the JSON parser as an option or flag value.

If the input cannot be interpreted as valid JSON, @JsonParse returns @ERROR.
The error message contains the position of the error within the JSON data, as well as an error code and a description of the parser error.

TEXT/VSPECBINBUFFER INPUT:
JSON data to be parsed.
The JSON data must be encoded in UTF-8.

Example using TEXT:
HJSON:=@JsonParse("{\"Name\":\"Max Mustermann\",\"Age\":42}");

The resulting JSON structure is:
{
"Name":"Max Mustermann",
"Age":42
}

The returned handle can then be used:
NAME:=@JsonGet(HJSON;"Name");
AGE:=@JsonGet(HJSON;"Age");
@JsonRelease(HJSON);

FN OPTIONS:
Optional numeric option or flag value for the JSON parser.
If OPTIONS is omitted, the value 0 is used and the JSON is processed using the parser’s default options.
The specified flags are passed unchanged to the underlying JSON parser and can be combined, where supported by the parser.

BIT DEC HEX MEANING if set
01 000001 00001 JSON_REJECT_DUPLICATES
02 000002 00002 JSON_DISABLE_EOF_CHECK
03 000004 00004 JSON_DECODE_ANY
04 000008 00008 JSON_DECODE_INT_AS_REAL
05 000016 00010 JSON_ALLOW_NUL

For normal processing of a JSON object or JSON array, specifying OPTIONS is usually not required.

JSON Object:
A JSON object can be created directly from TEXT:

JSONTEXT:="{\"Name\":\"Max Mustermann\",\"Active\":true,\"Value\":12.5}";
HJSON:=@JsonParse(JSONTEXT);
NAME:=@JsonGet(HJSON;"Name");
ACTIVE:=@JsonGet(HJSON;"Active");
VALUE:=@JsonGet(HJSON;"Value");
@JsonRelease(HJSON);

The JSON structure is:
{
"Name":"Max Mustermann",
"Active":true,
"Value":12.5
}

JSON Array:
A JSON array can also be parsed directly:

HJSON:=@JsonParse("[\"A\",\"B\",\"C\"]");
VALUE1:=@JsonGet(HJSON;0);
VALUE2:=@JsonGet(HJSON;1);
VALUE3:=@JsonGet(HJSON;2);
@JsonRelease(HJSON);

The resulting JSON structure is:
["A","B","C"]

Since JSON arrays use zero-based indexing, VALUE1 contains "A", VALUE2 contains "B", and VALUE3 contains "C".

VSPECBINBUFFER as INPUT:
JSON data can also be read from a VSPECBINBUFFER.

In this case, exactly the number of bytes specified by USEDSIZE (see @GetBufferInfo) are passed from the buffer to the JSON parser.
This is particularly useful for JSON data received, for example, via HTTP or REST.
The buffer must contain valid UTF-8 JSON.
Any terminating NULL byte (0x00) must not be included in USEDSIZE, because with a VSPECBINBUFFER all bytes specified by USEDSIZE are interpreted as part of the JSON input.

For example, if a buffer contains:
7B 22 41 22 3A 31 7D 00
this corresponds to:
{"A":1}\0

For parsing, USEDSIZE must in this case include only the bytes of:
{"A":1}
An additional 0x00 passed to the parser may cause a parser error.

Error handling:
If the input cannot be interpreted as valid JSON, @JsonParse returns @ERROR.

The error message has the following format:
INVALID JSON AT LINE <line>, COLUMN <column>, POSITION <position>: ErrorCode:<code> <description>

For example, invalid input such as:
{"Name":"Max Mustermann","Age":42
may result in an error message of the following form:
INVALID JSON AT LINE 1, COLUMN …, POSITION …: ErrorCode:… …

The fields have the following meaning:
LINE Line in which the error was detected
COLUMN Column within the line
POSITION Position within the input data
ErrorCode Numeric error code of the JSON parser
description Description of the parser error

This allows syntax errors, invalid UTF-8 data, or incomplete JSON structures to be located more precisely.

Notes:
@JsonParse does not perform any character set conversion. The input data must already be valid UTF-8.
In particular, data from TEXT fields that is originally encoded in LMBCS must not be treated as UTF-8 JSON without prior conversion.
The VSPECHJSON (HJS) handle returned by @JsonParse owns its own reference to the created JSON structure and must be released with @JsonRelease after use.

Example: @JsonParse(INPUT);

JSONTEXT:="{\"Name\":\"Max Mustermann\",\"Age\":42,\"Active\":true,\"Values\":[10,20,30]}";
HJSON:=@JsonParse(JSONTEXT);
NAME:=@JsonGet(HJSON;"Name");
AGE:=@JsonGet(HJSON;"Age");
ACTIVE:=@JsonGet(HJSON;"Active");
VALUES:=@JsonGet(HJSON;"Values";"L");
@JsonRelease(HJSON);

The resulting JSON structure is:
{
"Name":"Max Mustermann",
"Age":42,
"Active":true,
"Values":[10,20,30]
}

The return values are:
NAME "Max Mustermann"
AGE 42
ACTIVE 1
VALUES 10, 20, 30

VALUES is returned as a FLOATLIST by @JsonGet using the "L" option.

Note : This text was machine-translated and may contain inaccuracies.