Implicit and explicit JSON conversion for primitive types

This topic describes how primitive 4GL values are converted during JSON serialization and deserialization, and compares the behavior of json.Serializer and util.JSON.

For detailed comparisons and examples, refer to the tables in the sections dedicated to each data type.

BOOLEAN

Table 1. Serialization BDL to JSON
4GL value	JSON output	json.Serializer	util.json
`TRUE`	`true`	OK	OK
`FALSE`	`false`	OK	OK
`"true"` (`STRING` to `FGL-Boolean` assignment)	`null`	ERROR (unless authorized by serializeNullAsDefault)	OK

Table 2. Deserialization JSON to BDL
JSON input	Result	json.Serializer	util.json	Notes
`true`	`1`	OK	OK	Direct mapping
`false`	`0`	OK	OK	Direct mapping
`"true"`	`1`	ERROR	OK	Implicit `JSON-String` to `FGL-Boolean` ¹
`"false"`	`0`	ERROR	OK	Implicit cast `JSON-String` to `FGL-Boolean` ¹
`1`	`1`	ERROR	OK	Implicit cast: `JSON-Integer` to `FGL-Boolean` ¹
`0`	`0`	ERROR	OK	Implicit cast ¹
`"1"`	`1`	ERROR	OK	Implicit `JSON-String` to `FGL-Boolean` ¹
`"0"`	`0`	ERROR	OK	Implicit cast `JSON-String` to `FGL-Boolean` ¹
`"toto"`	-	ERROR	OK silent cast to `NULL`	`util.json` casts to `NULL` without raising an error.
`"toto"` and with `allowImplicitConversion = 1`	-	ERROR	OK silent cast to `NULL`	allowImplicitConversion does not help.
`{}` object	-	ERROR	ERROR
`[]` array	-	ERROR	ERROR

For behavior when using the permissive util.JSON parser, refer to JSON to BDL type conversion rules.

1. Implicit conversion in json.Serializer was removed in version 6.00.00.

FGL-Integer / FGL-Number

The term FGL-Integer refers to the 4GL types: TINYINT, SMALLINT, INTEGER, and BIGINT. A JSON number with a decimal part of zero (for example, 12.0000) is considered valid for FGL-INTEGER if no fractional digits remain after parsing.

The term FGL-Number in this document refers to all 4GL types: DECIMAL, MONEY, FLOAT, and SMALLFLOAT. When serialized to JSON, these are represented as JSON number.

Table 3. Serialization BDL to JSON
4GL value	JSON output	json.Serializer	util.json
`123`	`123`	OK	OK
`123.45`	`123.45`	OK	OK

Table 4. Deserialization JSON to BDL
JSON input	Target type	Result	json.Serializer	util.json	Notes
`12`	`FGL-Integer`	12	OK	OK
`12.000`	`FGL-Integer`	12	OK	OK
`12.35`	`FGL-Integer`	12	ERROR	OK	Truncation, not rounding ²
`"123"`	`FGL-Integer`	123	ERROR	OK	Implicit `JSON-String` to `FGL-Integer` ²
`"123.5"`	`FGL-Integer`	123	ERROR	OK	Implicit `JSON-String` to `FGL-Integer` ²
`12`	`FGL-Number`	12	OK	OK
`12.35`	`FGL-Number`	12.35	OK	OK
`"12.35"`	`FGL-Number`	12.35	ERROR	OK	Implicit `JSON-String` to `FGL-Integer` ²
`"toto"`	`FGL-Integer` `FGL-Number`	-	ERROR	OK silent cast to `NULL`	Invalid conversion
`true/false`	`FGL-Integer` `FGL-Number`	1 / 0 1.0 / 0.0	ERROR	OK silent cast to NULL	Type mismatch `json.Serializer:` allowImplicitConversion enables JSON-Boolean =>JSON-Integer/Number
`{}`	`FGL-Integer` `FGL-Number`	-	ERROR	ERROR
`[]`	`FGL-Integer` `FGL-Number`	-	ERROR	ERROR

For permissive parsing rules and implicit casting behavior provided by util.JSON, refer to JSON to BDL type conversion rules.

2. Implicit conversion in json.Serializer was removed in version 6.00.00.

FGL-String

The term FGL-String refers to 4GL string types: STRING, CHAR, VARCHAR, TEXT, BYTE. When serialized to JSON, these are represented as JSON string values.

Table 5. Serialization BDL to JSON
4GL value	JSON output	json.Serializer	util.json
`"abc"`	`"abc"`	OK	OK
`""` (empty)	`""`	OK	OK

Table 6. Deserialization JSON to BDL
JSON input	Result	json.Serializer	util.json	Notes
`""`	`""`	OK	OK	Empty string preserved
`"hello"`	`"hello"`	OK	OK
`123`	`"123"`	ERROR	OK	Implicit cast JSON-Integer to FGL-String ³
`true/false`	`"true"/"false"`	ERROR	OK	Implicit cast JSON-Boolean to FGL-String ³
`{}`	-	ERROR	ERROR
`[]`	-	ERROR	ERROR

For permissive JSON parsing behavior provided by util.JSON, refer to JSON to BDL type conversion rules.

3. Implicit conversion in json.Serializer was removed in version 6.00.00.

DATE

Table 7. Serialization BDL to JSON
4GL value	JSON output	json.Serializer	util.json	Format
`TODAY`	`"2025-12-11"`	OK	OK	OK – ISO-8601 like (`YYYY-MM-DD`)

Table 8. Deserialization JSON to BDL
JSON input	Result	json.Serializer	util.json	Notes
`""`	NULL	OK	OK
`"2025-05-16"`	`"05/16/2025"`	OK	OK	Valid ISO-like format
`"16/05/2025"`	-	ERROR	OK silent cast to `NULL`	Not supported
`"05/16/2025"`	-	ERROR	OK silent cast to `NULL`	US format not accepted
`"not-a-date"`	-	ERROR	OK silent cast to `NULL`
`{}`	-	ERROR	ERROR
`[]`	-	ERROR	ERROR

For JSON parsing behavior using the util.JSON class, refer to JSON to BDL type conversion rules.

DATETIME

Table 9. Serialization BDL to JSON
4GL value	JSON output	json.Serializer	util.json	Notes
`CURRENT YEAR TO SECOND`	`"2025-12-11 14:23:01"`	OK	OK	Not ISO-8601 compliant yet. ⁴

4. We do a regex check for the format: \d{4}-\d{2}-\d{2}\d{2}:\d{2}:\d{2}

Note:

ISO 8601 format with 'T' separator is not yet supported in json.Serializer but will be in the future.

Table 10. Deserialization JSON to BDL
JSON input	Result	json.Serializer	util.json	Notes
`"2025-05-16 14:23:01"`		OK	OK
`"2025-05-16T14:23:01"`	`2025-05-16 14:23:01`	OK	OK	Convert to FGL format
`"not-a-date"`	-	ERROR	OK silent cast to `NULL`
`{}`	-	ERROR	ERROR
`[]`	-	ERROR	ERROR

For JSON parsing behavior using the util.JSON class, refer to JSON to BDL type conversion rules.