The z/OS JSON parser

The JSON parser portion of the z/OS® client web enablement toolkit provides a generic, native z/OS JavaScript Object Notation (JSON) parser for z/OS applications.

JSON is a text-based open standard designed for human-readable data interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. It is language-independent, with parsers available for many languages. JSON is described in https://www.json.org/. The official Internet media type for JSON is application/json. The JSON format is often used for serializing and transmitting structured data over a network connection. It is primarily used to transmit data between a server and web application, serving as an alternative to XML. JSON data representation is becoming more pervasive across the industry due to its simplicity and ease of use.

Both JSON and XML are recommended formats for the representation of a request/response body when programming an application following the principles of REST. The XML System Services component of z/OS (z/OS XML) provides a system-level XML parser that is integrated with the base z/OS operating system. (For more information, refer to z/OS XML System Services User's Guide and Reference.) It is intended for use by system components, middleware, and applications that need a simple, efficient XML parsing solution. Likewise, the z/OS JSON parser provided with the z/OS client web enablement toolkit is an equivalent system-level, general-purpose JSON parser that is integrated with the z/OS operating system and that works in any native z/OS environment.

JSON basics

The designation of JSON as a great data exchange format lies in its innate simplicity. There are only a few types of data (string, number, boolean, null, array, and object) and its data structures mirror many of the modern programming languages. Many resources are available for you to consult on the Internet to help you gain a basic understanding of the easy-to-use syntax.

An important JSON concept to understand is the idea of an object entry. Within an object, there can be one or more unordered object entries. Each entry consists of a name/value pair. The name, represented by a string enclosed in double quotation marks, identifies the value portion of the pair. The value can be any valid JSON data type.

Figure 1 shows an example of JSON text.

Figure 1. Example of JSON text
{
  "firstName": "Steve",
  "lastName": "Jones",
  "age": 46,
  "address": {
    "streetAddress": "123 Anywhere Ave",
    "city": "Poughkeepsie",
    "state": "NY",
    "postalCode": "12601",
    "country": "USA"
  },
  "phone": [
    {
      "type": "mobile",
      "number": "914 555 5555"
    },
    {
      "type": "home",
      "number": "845 555 1234"
    }
           ]
  }

In Figure 1, "firstName", "lastName", "age", "address", and "phone" are all names of object entries in the main (root) object of the JSON text. The values assigned to the "firstName", "lastName", and "age" object entries are all simple data types (string, string, and number, respectively). The named entries "address" and "phone", however, contain a more complex data type as their values. The "address" entry nests additional address details within another object, which contains the portions of an address. The "phone" entry contains an array made up of two array entries. Array entries differ from object entries in that arrays contain only a value (of any JSON data type). In this case, the array values are two objects, each of which group specific types of phone numbers together.

Comments in JSON text

Start of changeStart of changeIn addition to the well recognized data types, the z/OS JSON parser also tolerates single and multi-line comments defined by the JSON5 Data Interchange Format extension to JSON (https://spec.json5.org/#comments).End of change Comments can be either single line or multi-line as shown in the following examples:End of change

Start of change
Figure 2. Example of JSON single line comment
//single line comment starts with a double-solidus and ends with a line terminator
//the supported line terminator character is a Line Feed<LF>:
//IBM-1047 -> hex 15
//UTF-8 -> hex 0A
End of change Start of change
Figure 3. Example of JSON multi-line comment on one line
/* multi-line comment on a single line, uses a solidus + asterisk form */
End of change Start of change
Figure 4. Example of JSON multi-line comment
/* multi-line comments start with solidus + asterisk,
    and can span arbitrarily-many lines,
    until ended with an asterisk + solidus like this */
End of change

Start of changeComments themselves are allowed to surround and, depending on the style, can even be placed in between the name and the value. However, comments can not be embedded inside either the name or value, and nested comments are not supported.End of change

Start of changeIn the following example, comments are indicated in bold:End of change

Start of change
Figure 5. Example of comments on JSON data
/***** Testing All  *******************************
 * All attributes are tested inside their        *
 * condition and displayed with send/log         *
 * message. All modifiable attributes are then   *
 * modified within their own condition def       * 
 * then standard actions                         *
 ************************************************/
{
/******** Testing CompletionCode ***************/
  "condition" : " String(CompletionCode) = '()' "
 ,"actions" :
    [
      {
         "action" : "sendMessage" //first action
         ,"message": /*CC? */" 'CompletionCode: '||String(CompletionCode)"
      }
     ]
}
End of change