JSON to Genero BDL conversion rules

The JSON utility classes implement methods that can fill a Genero BDL RECORD or DYNAMIC ARRAY. This topic describes how JSON data is converted to Genero BDL data.

The destination record or array must have the same structure as the JSON source data.

Each JSON element is assigned to a record member by name, not by position. Elements in the JSON string can be at a different ordinal position as the corresponding members in the destination record.

Element name matching is case-insensitive. For example, if the Genero BDL record member is defined as CustNo, and the JSON data string contains the "custno":999 name/value pair, the value will be assigned. However, since Genero BDL record member names are used as-is to write JSON data, is it strongly recommended to define the Genero BDL records with the exact names used in JSON data string.

Elements in the JSON string that do not match an Genero BDL record member are ignored; no error is thrown if there is no corresponding Genero BDL member.

Genero BDL record members that have no matching JSON element are initialized to NULL.

Important: JSON specifications allow you to define element names with characters that cannot be used in Genero BDL identifiers. For example, a JSON element name can be "customer.name" or "customer:name", however it is not possible to define a program variable with these same names. To work around this issue, define the record elements with underscores in place of unsupported characters, and before assigning the JSON string to the Genero BDL record, replace all element names by the corresponding record member names (using base.StringBuffer.replace to do the replacements).

The JSON value must match the data format of the destination member. If the value does not correspond to the type (for example, if the JSON value is a character string while the target record member is defined with a numeric type), the target member will be set to NULL.

JSON arrays delimited by square brackets are used to fill a program array of the destination record. The destination array should be a dynamic array. If the array is defined as static, the additional elements of the source JSON array will be discarded, while missing elements will be initialized to NULL.

The JSON source string must follow the JSON format specification. It can contain multilevel structured data. If the source string is not well formatted, the runtime system will throw error -8109.

Table 1. JSON to Genero BDL type conversion rules
Target Genero BDL type	Description
`BOOLEAN`	The JSON value should be `null`, `true` or `false`. If the JSON value is a number or a string, the language conversion rules from number/string to `BOOLEAN` apply.
`TINYINT`, `SMALLINT`, `INTEGER`, `BIGINT`, `SMALLFLOAT`, `FLOAT`, `DECIMAL`, `MONEY`	A JSON number can be assigned to any language numeric type. The limits of the target type cause potential overflows errors. On error the target variable will be initialized to `NULL`, the parser continues without an error.
`DATE`	The JSON value must be a string formatted as `"YYYY-MM-DD"`.
`DATETIME`	If the value is a JSON string, it must be formatted as `"YYYY-MM-DD hh:mm:ss.fffff"`, or represent as an ISO 8601 formatted date-time, in UTC (with Z indicator) or with a timezone offset (+/-hh[:mm]). For example: `"2013-02-21T15:18:44.456Z"`, `"2013-02-21T20:18:44.456+02:00"`. If the value is a JSON number, it is interpreted as UNIX™ time (seconds since the Epoch 00:00:00 UTC, January 1, 1970). Note that the `YYYY-MM-DD hh:mm:ss.ffff` format is used to represent the local time. When exchanging date-time values in communications across different time zones, consider to convert date-time values to Coordinated Universal Time (UTC), by using the `util.Datetime` methods.
`INTERVAL`	The JSON valid must be a string formatted as "`YYYY-MM`" or "`DD hh:mm:ss.fffff`", according to interval class of the target variable.
`BYTE`	The JSON string value must be encoded in Base64. The Base64 encoding is described in [RFC4648].
`TEXT`, `CHAR`, `VARCHAR`, `STRING`	If the value is a number, the result string uses the locale specific decimal point. Any character in the Basic Multilingual Plane (U+0000 through U+FFFF) may be escaped: `\u` followed by exactly 4 hexadecimal digits (`[0-9a-fA-F]`). The hexadecimal digits encode the code point. Escaping of characters outside the Basic Multilingual Plane my be escaped by there UTF-16 surrogate pairs. Example: This is the representation of the G clef character (`U+1D11E`) "`\uD834\uDD1E`".