JSON serialization

It is possible to serialize out JSON data contained in a JsonObject to a JSON string by calling one of the toJsonString or toPrettyJsonString methods on the JsonObject class. As with JSON parsing, it is possible to perform JSON serialization with, or without, a schema.

Schema-driven serialization

JSON data serialized with a schema uses the schema to determine the output format for a property as well as to validate that the data conforms to the declared schema. Scalar value output formats are defined in JSON data types and formats. Handling of null values during serialization depends upon the serialization options that you are using.

Validation and error reporting

Schema-driven serialization can result in validation errors being reported in the following circumstances:

The runtime value of a property in the JsonObject does not match the type of property defined within the schema. This circumstance can arise if a scalar value is present where a JsonObject or List is expected or if the scalar value is the wrong type of Java object.
A property in the JsonObject does not match any property defined in the associated JSON schema definition, and the schema definition does not define the additionalProperties property.
A property contains a null value, the property does not specify x-gw-nullable as true, and the serialization options specify the inclusion of null properties.

If any validation errors are found during serialization, the REST framework throws an exception.

Schemaless serialization

Serialization without a schema transforms JsonObject objects into JSON objects and lists of JSON objects into JSON arrays. For any other runtime value type, if the value type has a default JSON mapping as defined in JSON data types and formats, the REST framework uses that JSON data type to serialize the value. Otherwise, if the framework cannot serialize the value, it reports a validation error, resulting in an exception.

Serialization Options

JSON serialization can accept a JsonSerializationOptions object, which has the following behavior. If the toJsonString or the toPrettyJsonString method is being invoked explicitly, the calling code can pass these options in directly. If the REST API framework invokes the method during serialization, PolicyCenter sets the serialization options based upon the values configured in the Swagger schema and runtime request headers. The following table summarizes the serialization options and how they behave:

Option	Default	Behavior
includeNullProperties	`false`	If `true`, `null` property values are preserved. If `false`, `null` properties are undefined in the output.
includeNullItems	`false`	If `true`, the REST framework preserves the `null` item values in arrays. If `false`, the REST framework omits `null` items from array values. In addition, the framework considers an array that contains only `null` items to be empty and handles the empty array depending upon the value of the includeEmptyArrays property.
includeEmptyArrays	`true`	If `true`, empty arrays for properties are preserved. If `false`, empty arrays are treated as if the property value was `null`, subject to the value of the includeNullProperties option.
includeSchemaProperty	`false`	Includes the $GW-Schema property on the root object. This property includes the value of the fully-qualified schema definition name for the root object.
includeCorrelationId	`false`	Currently ignored for JsonObject serialization.
includeTimestamp	`false`	Currently ignored for JsonObject serialization.
includeUser	`false`	Currently ignored for JsonObject serialization.
includeServer	`false`	Currently ignored for JsonObject serialization.
validateOutput	`false`	If `true`, the REST framwork validates the data against property-level constraints such as minLength, the set of required fields on the object, and any custom validators.