Primitive type serialization

This section focuses on implicit/explicit conversion comparisons for JSON serialization and deserialization of primitive types. It outlines the rules for serialization and deserialization, type casting, and failure scenarios, and highlights the differences between 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)	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`	OK	OK	Implicit `JSON-String` to `FGL-Boolean` ¹
`"false"`	`0`	OK	OK	Implicit cast `JSON-String` to `FGL-Boolean` ¹
`1`	`1`	OK	OK	Implicit cast: `JSON-Integer` to `FGL-Boolean` ¹
`0`	`0`	OK	OK	Implicit cast ¹
`"1"`	`1`	OK	OK	Implicit `JSON-String` to `FGL-Boolean` ¹
`"0"`	`0`	OK	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

1. This implicit conversion behavior may be restricted in a future version.

INTEGER / DECIMAL (NUMBER)

The term FGL-Number refers to all 4GL numeric types: DECIMAL, MONEY, FLOAT, and SMALLFLOAT. When serialized to JSON, these are represented as JSON 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 INTEGER if no fractional digits remain after parsing.

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.35`	`FGL-Integer`	12	OK Should only be accepted if it is a decimal followed by a 0 (for example 12.000) ²	OK	Truncation, not rounding ²
`"123"`	`FGL-Integer`	123	OK	OK	Implicit `JSON-String` to `FGL-Integer` ²
`"123.5"`	`FGL-Integer`	123	OK	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	OK	OK	Implicit `JSON-String` to `DECIMAL` ²
`"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 (unless `allowImplicitConversion`)	OK silent cast to NULL	Type mismatch
`{}`	`FGL-Integer` `FGL-Number`	-	ERROR	ERROR
`[]`	`FGL-Integer` `FGL-Number`	-	ERROR	ERROR

2. This implicit conversion behavior may be restricted in a future version.

STRING

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
`"hello"`	`"hello"`	OK	OK
`123`	`"123"`	OK	OK	`json.Serializer`: This implicit conversion behavior may be restricted in a future version.
`true/false`	`"true"/"false"`	OK	OK	`json.Serializer`: This implicit conversion behavior may be restricted in a future version.
`{}`	-	ERROR	ERROR
`[]`	-	ERROR	ERROR

DATE

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

Table 8. Deserialization JSON to BDL
JSON input	Result	json.Serializer	util.json	Notes
`"2025-05-16"`	`"05/20/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

DATETIME

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

3. 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 silent cast to `NULL`	Convert to FGL format
`"not-a-date"`	-	ERROR	OK silent cast to `NULL`
`{}`	-	ERROR	ERROR
`[]`	-	ERROR	ERROR