JSON parsing and validation

You can parse JSON data by invoking one of the parse methods on the JsonObject class or a generated JsonWrapper subclass. Parsing can be done in the context of a specific JSON schema definition. In this case, the data is validated and deserialized according to that schema. The data can also be parsed without a schema. In this case, no validation is performed. In addition, only a limited number of primitive types are used for deserialization. Deserialization and validation are done in a single step. A parser handles this step in order to maximize efficiency.

Schema-driven parsing

If a JsonSchemaDefinition is supplied to the parser, the REST framework uses the schema to drive deserialization and validation of the data.

Data types
The REST framework deserializes a given JSON property value based on an associated JsonSchemaProperty type:
  • It deserializes object properties into JsonObjects.
  • IT deserializes scalar property values into the type determined by the properties type, format, and x-gw-type, as specified in JSON data types and formats.
  • It deserializes array properties into lists of JsonObjects or scalar Java types, as appropriate.
Note: For the sake of client libraries written in JavaScript, values that map to a JSON integer type can have trailing decimal 0s. The REST framework still considers these values valid integers or longs. For example, suppose that a property is of type integer and that the property format is int32. In this case, the REST framework deserializes each of 100, 100.0, and 100.00 as the integer value 100.
Constraint validation
JSON schema property definitions can define various constraints on a property value that can be used to validate the length of a property that deserializes as a String. For example, these constraints include the maxLength or minLength properties. Simple scalar constraints that are validated as property values are deserialized. Validation takes place against the deserialized values rather than the raw JSON values. Most of the validations are straightforward. Validation behavior is defined in JSON schema file specification. However, a few specific constraints have more complex behavior:
  • If JSON data contains an explicit null value for a property or element within an array, the data is valid if and only if the properties or items involved declare x-gw-nullable to be true.
  • If a schema definition defines required properties, these properties must be defined on the object; an explicit null value still counts as a property being defined for purposes of required property validation.
  • Schema properties that specify readOnly as true are rejected if the deserialization options specify the rejectReadOnlyProperties option.
  • Properties on the input that are not defined on the schema can either be rejected, logged, or ignored based on the value of the unknownPropertyHandling option in the deserialization options.
Custom validators

Custom validators for properties, items, and objects are invoked after the containing object has been fully parsed and deserialized.

Deserialization options
There are currently two different options that can be set while parsing and deserialization JSON data with the JsonDeserializationOptions class:
unknownPropertyHandling
This option determines what the framework does when it encounters properties on a JSON object that do not match a property in the schema. You can set this option to ignore, log, or reject, with ignore being the default value. The value is set automatically by the REST API framework, based upon the value of the GW-UnknownPropertyHandling request header or request property:
  • If you set option unknownPropertyHandling to ignore, the framework deserializes the property values that do not match the schema and adds the property values to the resulting JsonObject.
  • If you set option unknownPropertyHandling to log, the framework deserializes the property values still. In addition, the framework logs an INFO-level message.
  • If you set option unknownPropertyHandling to reject, the framework reports a validation error for the property.
rejectReadOnlyProperties

This option determines whether the framework reports those properties whose schema specifies readOnly as true as validation errors. The default value is false. The REST API framework sets this value to true while parsing the body of a request.

Error reporting
Suppose a JSON object to be parsed is not well-formed JSON. That is, the JSON object cannot be parsed at all. In this case, an exception is thrown. Otherwise, any validation issues are reported back in the supplied JsonValidationResult object. Note that many of the variants of the JsonObject.parse method implicitly ignore validation errors.

Schemaless parsing

If you do not supply a schema during JSON parsing, the framework uses the default rules to deserialize the JSON data. The resulting set of primitive data types is very limited and corresponds to the limited set of JSON primitive types.

Data types
JSON Type Java Type
array List
object JsonObject
boolean Boolean
integer
  • Integer if the integer is less than MAX_INT
  • Long if the integer is greater than or equal to MAX_INT and less than MAX_LONG
  • BigInteger if the integer is greater than MAX_LONG
number Double
string String
Error reporting

If the JSON to be parsed is not well-formed JSON, the framework throws an exception. Otherwise, the framework parsing completes successfully with no reported validation issues.