JavaScript Object Notation (JSON) parser

Edit online

You can use JavaScript Object Notation (JSON) parsing with IBM Sterling Transformation Extender Design Studio to accept a JSON document as a type tree.

Design Studio accepts a JSON document as type tree input, and creates an MTX file from the JSON document that shows all the fields in the structure that is contained in the JSON document. Depending on the data in the JSON document, two field types are supported (text and numeric). Boolean field types are displayed as text field types with true or false as the data. Any field that contains a null value is considered a text field.

Additionally, JSON documents include two JSON group types, JSON arrays and JSON objects. The default attribute for both group types is unordered (which is the default), but you can also select a sequenced attribute. Choosing the sequenced attribute causes IBM Sterling Transformation Extender to process the document in sequence order, which ameliorates any confusion that can occur with unordered processing. To change an attribute from unordered to sequenced, select the Set Default Group Class as sequenced option on the Native JSON Customization page and click Finish.

Important: Native JSON converts invalid type tree characters such as : and . to ~. Additionally, reserved words such as any, component, false, in, last, none, true, and where are prefixed by a number sign (#). If a field cannot be found in the type tree at the level of the data during parsing, and no any type field is found, the parse fails with the message Could not find type to assign JSON data. All escaped characters except \u four-hex-digits are converted into actual values on input and then converted to escape characters on output. However, hex digits are not converted because they cannot be converted back on output. The validation that is performed by the JSON parser is minimal because only numeric fields need to be validated. All numeric fields have an optional leading sign and an optional decimal point. Exponential numeric fields are not supported in the core engine and fail validation. Trace and audit functions are almost identical to the IBM Sterling Transformation Extender native core engine parse, except when the JSON Parser is parsing and outputting JSON data. When JSON data fails parsing or validation, you receive a detailed message of what error occurred and where the erroneous data is in the structure. Entries in the trace file appear for all data points and groups.

You can also add an AnyType group field to any level of the JSON document. The anytype group field contains two fields, a name fields and a data text field, which allows the JSON tree to handle data that was not in the original document. When you use the AnyType field, any type of data is mapped to the field. To add AnyType group fields to the JSON document, select the Add AnyType fields to every level option on the Native JSON Customization page and click Finish.

Important: Your sample JSON document must include all the fields that might occur.

Guidelines for the JSON prototype object schema file

You must follow these guidelines when you create the JSON prototype object schema file:

  • The JSON file that you use for IBM Sterling Transformation Extender native JSON processing must be a prototype object that best represents the data you plan to use.
  • Ensure that all fields are defined in the JSON file.
  • When you use arrays, ensure that all fields that to be used in that array are defined in the first iteration of that array.
  • When you use native JSON to define the main input or output card, always select the main Type as the first JSON type.
    Note: The main input or output card is the card that has the file or other source that defines how to parse or create the document.
  • The encoding field on input always returns the value NONE. On output, this field can be set to any valid JSON encoding and the JSON document is produced that uses that encoding. If you do not configure the encoding, the default encoding used is UTF-8.