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.
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
In 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). Comments can be either single line or multi-line as shown in the following examples:
Comments 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.
In the following example, comments are indicated in bold: