json_null handling

This section focuses on the key differences in handling null or empty values between json.Serializer and util.json when the json_null attribute is used.

The handling of the json_null attribute and schema-related features differs significantly between util.json and json.Serializer:

  • util.json

    • The json_null attribute only affects serialization (BDL to JSON).
    • At the root level, a missing value is implicitly treated as null.
    • Ignores schema-related attributes such as JSONRequired at runtime.

  • json.Serializer

    • The json_null attribute affects both serialization (BDL to JSON) and deserialization (JSON to BDL).
    • At the root level, a missing value is considered an error, even if json_null="undefined" is set.
    • Performs field presence validation and handles default values during deserialization.
    • Processes and enforces schema-related attributes such as JSONRequired.

For more information about managing null with the json_null attribute, go to NULLs and empty structures.

Recommended practice

When using json.Serializer:
  • Avoid relying on json_null="undefined" at the root level.
  • If the root value may be omitted, wrap the primitive type inside a RECORD to ensure proper control and prevent deserialization errors.
For detailed comparisons and examples, refer to the tables below that are dedicated to null handling for both APIs.
Table 1. Serialization of NULL / omitted values
Value is NULL Target type json.Serializer util.JSON Notes
(default)
Primitive type Omitted Omitted json.Serializer: ERROR if root

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 {} / [] {} / [] json.Serializer: ERROR if root
json_null="null"
Primitive type null null

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 null null
json_null="undefined"
Primitive type Omitted Omitted undefined at root is treated as null

json.Serializer: ERROR if root

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 Omitted Omitted undefined at root is treated as null

json.Serializer: ERROR if root
JSONRequired
Primitive type ERROR Omitted util.JSON ignores attribute JSONRequired

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 {} / [] {} / [] util.JSON ignores attribute JSONRequired
JSONRequired + json_null="null"
Primitive type null null util.JSON ignores attribute JSONRequired

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 null null util.JSON ignores attribute JSONRequired
JSONRequired + json_null="undefined"
Primitive type ERROR null util.JSON ignores attribute JSONRequired

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 ERROR null util.JSON ignores attribute JSONRequired
Table 2. Deserialization of Omitted / NULL values
Incoming Value Target type Attribute json.Serializer util.JSON Notes
Omitted
Primitive type OK OK ERROR if root

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 OK OK ERROR if root
null
Primitive type ERROR OK

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 ERROR OK
Omitted
Primitive type json_null="null" OK OK ERROR if root

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 json_null="null" OK OK ERROR if root
{} / []

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 OK OK
null
Primitive type json_null="null" OK OK

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 json_null="null" OK OK
Omitted
Primitive type json_null = "undefined" OK OK ERROR if root

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 json_null = "undefined" OK OK ERROR if root
Omitted
Primitive type JSONRequired ERROR OK util.JSON ignores attribute JSONRequired

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 JSONRequired ERROR OK util.JSON ignores attribute JSONRequired
null
Primitive type JSONRequired ERROR OK

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 JSONRequired ERROR OK
Omitted
Primitive type JSONRequired + json_null="null" OK OK

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 JSONRequired + json_null="null" OK OK
Omitted
Primitive type JSONRequired + json_null="undefined" ERROR OK json.Serializer: "undefined" should be treated as json_null="null" at the root level

FGL-Object

util.JSONObject

FGL-Array

util.JSONArray

 JSONRequired + json_null="undefined" ERROR OK json.Serializer: "undefined" should be treated as json_null="null" at the root level