You are currently on IBM Systems Media’s archival website. Click here to view our new website.


An RPGer’s First Steps With JSON


JSON (JavaScript Object Notation) is fast becoming an essential technology in modern IBM i shops. From web services to browser interfaces and data exchange—it has seen a remarkable growth in usage over the last few years. In recent times IBM have even added direct JSON support to DB2 - a topic we may return to another day.

JSON began basically as a replacement for XML in Ajax calls. That’s somewhat ironic when you consider that the "x" in Ajax actually stands for XML—“Asynchronous Javascript and XML."

XML had proven just too big and lumpy, requiring too much horsepower to parse in Web 2.0 type applications. JSON on the other hand is not only far more compact than XML, but because it is modelled on Javascript's own data definitions, a fast parser was already effectively built into every browser. So there was very little additional support needed in the browser. JSON also only uses UTF-8 encoding and so the multiple data encodings supported by XML do not have to be dealt with. With this three-fold advantage (compactness, ease of parsing, everything in UTF-8) it was hardly surprising that JSON rapidly replaced XML in most Ajax calls. From there it has gone on to become the vehicle of choice for web service requests and responses, and is rapidly entering the realm of data interchange.

JSON Syntax Basics

So, let's begin this brief introduction by looking at the basic rules for formatting JSON. JSON data consists of a series of name/value pairs with colons acting as the separator between the name and the value. Individual elements within a series are separated by commas and names must always be in quotes. So JSON data has this basic form:

	"name1" : value_1, "name2" : value_2, ... "namen" : value_n

The actual value portion of the name/value pair can be more than just a simple number or string. In fact it can be any of the following:

  • Number (integer or floating point)
  • String (enclosed in quotes)
  • Array
  • Object
  • Boolean true/false
  • or null.

Arrays are delineated by square brackets ( "[" and "]" ). Unlike RPG arrays, which are limited to containing multiple elements of the same type and size, JSON arrays can contain any type of value, including another array. Which in turn can contain an array, which can ... You get the picture.

Objects are delineated by curly braces ( "{" and "}" ) and can contain any other type of value including objects. Don't let the term "Object" confuse you - there is nothing OO about them. They are basically just RPG Data Structures (DS).

That's really all there is to it, other than to mention that if a string value contains a control character (of which quotes will probably be the most common) then it must be escaped by using the backslash ( "\" ) character in front of it. So to include a quote in a string you would code: "This value includes a \"quote\"" and similarly the "\" character would have to appear as "\\" in the string.

We may have over simplified things a little but hopefully you'll understand the basics. Unlike XML which has its rules very well documented (some might well say over documented!) information on the syntax rules for JSON can be hard to come by as it appears to inevitably be bound up in comparisons with Javascript. That’s fine if you are fully conversant with Javascript but we are not, and suspect that that is also true for many other RPGers.

Now that we have a basic understanding of the JSON syntax, let's look at a very simple example:

(A) {
(B) "employees" : [
(C) { "firstName":"John", "lastName":"Doe" },
    { "firstName":"Anna", "lastName":"Smith" },
    { "firstName":"Peter", "lastName":"Jones" }
(D) ]}

A. We begin with "{" - i.e. the data is an object. This is also known as the document root, or root node.

B. The first field's name is "employees" and its value is an array "["

C. The elements of the array are in turn objects, each one containing the values for "firstName" and "lastName". The commas separating out the individual fields.

D. Finally the document wraps up by closing the array ( "]" ) and then the root ( " } " ).

If we were to represent this data in an RPG DS it would look like this:

dcl-ds employees  Dim(3)  Qualified;
   firstName  Char(n);
   lastname   Char(n);

Ignoring, of course, any logic needed to initialize the values of the fields in the DS array. Plus we have to specify the number of elements in an RPG array.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters