JSON is relatively new as it was first described by Douglas Crockford in July 2006 in his IETF Request for Comments “The application/json Media Type for JavaScript Object Notation”[2]. In many respects JSON is similar to XML as both are text based data interchange formats used broadly in the Web. While XML has now became the whole family of related standards – including XML Namespaces, XML Schema, XSL, XPath and others – JSON defines only a small set of formatting rules for the portable representation of structured data.

The key strength of JSON is simplicity. Douglas Crockford describes JSON structure in his paper presented at XML 2006 Conference in Boston “JSON: The Fat-Free Alternative to XML” [3]:

The types represented in JSON are strings, numbers, booleans, object, arrays, and null.

JSON syntax is nicely expressed in railroad diagrams.

Hide image

JSON only has three simple types – strings, numbers and Booleans – and two complex types – arrays and objects.

A string is a sequence of zero or more characters wrapped in quotes with backslash escapement, the same notation used in most programming languages.

A number can be represented as integer, real, or floating point. JSON does not support octal or hex. It does not have values for NaN or Infinity. Numbers are not quoted.

A JSON object is an unordered collection of key/value pairs. The keys are strings and the values are any of the JSON types. A *** separates the keys from the values, and comma separates the pairs. The whole thing is wrapped in curly braces.

The JSON array is an ordered collection of values separated by commas and enclosed in square brackets.

The character encoding of JSON text is always Unicode. UTF-8 is the only encoding that makes sense on the wire, but UTF-16 and UTF-32 are also permitted.

JSON has no version number. No revisions to the JSON grammar are anticipated.

JSON has become the X in Ajax. It is now the preferred data format for Ajax applications. The most common way to use JSON is with XMLHttpRequest. Once a response text is obtained, it can quickly be converted into a JavaScript data structure and consumed by a program

JSON’s syntax is significantly simpler than XML, so parsing is more efficient.

JSON doesn’t have namespaces. Every object is a namespace: its set of keys is independent of all other objects, even exclusive of nesting. JSON uses context to avoid ambiguity, just as programming languages do.

JSON has no validator. Being well-formed and valid is not the same as being correct and relevant. Ultimately, every application is responsible for validating its inputs.

Below is a fragment of sample JSON text, based on “Sample Confabulator Widget” from [4], used in the later part of this article.

There is a big number of programming languages that have built-in support for JSON or libraries to work with JSON. These JSON bindings for different programming languages are listed on JSON homepage [4], including three open source Delphi libraries. Since Delphi 2010 the JSON support is part of the VCL library as implemented in the DBXJSON.pas unit.

In order to visualize Delphi classes responsible for JSON support, I have added the “DBXJSON” unit directly to a little test Delphi application, clicked on “Model Support” tab in Project Manager and got the following UML class diagram. Some of the classes from DBXJSON.pas unit not related directly to JSON support are not shown here.

Hide image

In Delphi 2007 the DBX database driver framework architecture has been reengineered in pure Delphi code and introduced a number of interesting features including extensible command types. In the next release – Delphi 2009 – the DBX architecture has been extended and DataSnap framework for building client/server and multi-tier application has been reengineered as well as the extension of the new DBX architecture. One of the most interesting and powerful capabilities introduced to DataSnap support in the following Delphi release – Delphi 2010 – were lightweight callbacks passed to DataSnap server methods for the server application to be able to call back into the client.

The DBXJSON.pas unit defines the abstract base class for callback objects that contains “Execute” method that accepts and returns parameters of TJSONValue type, thus making it possible to pass in and out arbitrarily complex data structures encoded as JSON. Here is the declaration of this class:

The DBXJSON unit contains also functionality to parse JSON text into the graph of TJSONValue-descedants and to generate JSON text from the graph of objects in memory. On the graphics “TJSONAncestor.Owned: Boolean” property has been expanded to underline the fact that all JSON descendants have the “Owned” property that controls the lifetime of JSON objects in memory.

TJSONObject class contains static method “ParseJSONValue” that effectively implements JSON parser functionality. It accepts a string parameter with JSON text and returns a TJSONValue reference to the root of the graph of TJSONAncestor-descendants.

It is also possible to generate JSON text from the in-memory tree of JSON objects calling “ToString” overloaded method on any of “TJSONAncestor” descendants.

Before Delphi 2010 introduced DBXJSON unit, I was trying to implement JSON parsing functionality manually coding JSON railroad diagrams. With DBXJSON implementation in place there is little point in reinventing the wheel; however there is still no design-time support for JSON. Everything has to be done in code. Hence the concept of creating a minimal VCL component wrapper for JSON parser implementation provided by “TJSONObject.ParseJSONValue” class method that accepts JSON text and returns the object tree representing JSON document structure in memory.

“TJSONDocument” component has been implemented inside “jsondoc” unit to keep some level of parity with its “TXMLDocument” component equivalent that is implemented inside “xmldoc” unit.

Below is the declaration of the “TJSONDocument” VCL component:

The full source code of this component and all other source code described in this paper can be downloaded from [1]. See “References” section at the end of this article.

The “TJSONDocument” contains published “JsonText: string” property that can be used to assign JSON text for parsing and “RootValue: TJSONValue” public property that can be used to assign “TJSONValue” reference and generate JSON text.

Assigning to any of these properties cause the other property to be updated and the “OnChange” event is fired every time the JSON stored inside the component is changed. In this way it is possible for other components of an application to be notified and refreshed. In this sense “TJSONDocument” component can be used as a JSON parser and generator as described in the original JSON RFC [2].

The public “IsActive: boolean” property returns true if TJSONDocument component contains valid JSON, or false it is empty.

The “TJSONObject.ParseJSONValue: TJSONValue” method is sensitive to the contents of the JSON text passed for parsing. If the string provided does not contain valid JSON text or it contains JSON text with additional whitespace characters, than it is always returning “nil” TJSONValue reference. The class function “StripNonJson” is used to remove from JSON text any non JSON characters and is implemented as follows using “TCharacter” class from the VCL “Character” unit.

The process of JSON parsing is implemented in “ProcessJsonText” method that is called as a side-effect of assigning to “JsonText: string” published property.

The “TJSONDocument” was designed to be as minimal as possible. For convenience it also surfaces “EstimatedByteSize: integer” method provided by the underlying DBXJSON implementation.

This is how the “TJSONDocument” component looks at design-time inside the Delphi 2010 Object Inspector.

Hide image

I have always wanted to implement a JSON viewer in DelphiJ The “TJSONDocument” component is non-visual, so I needed a separate visual component that would provide graphical, tree-representation of JSON. This component should have a “JSONDocument” published property to connect both components at design-time.

How JSON should be visualized? Is simple Delphi “TTreeView” component good enough or maybe I should do some fancy painting in code? Maybe I should use TVirtualTreeView component to have a tree with multiple columns?

These are all good questions, so I had to do a little googling around for inspiration. There are simpler and more complex JSON viewers available in Internet. Some of them are standalone applications, like the one coded in .NET and available at http://jsonviewer.codeplex.com/. Other viewers are embedded at web pages like http://www.jsonviewer.com/ or http://jsonviewer.stack.hu/. The one that I liked the most was implemented in Java and is available as a part of the Apache Pivot project for Rich Internet Applications (http://pivot.apache.org/demos/json-viewer.html). The one cosmetic thing that I do not like about it, is that is sorts JSON properties alphabetically and does not preserve the original ordering of object pairs.

Below is the screenshot from the apache pivot web page and this is my desired TreeView-based JSON viewer functionality:

Hide image

Here we goJ

I have decided to create my JSON tree view component as a descendant of Delphi VCL “TTreeView” component. A good Delphi programming practice would be to derive from “TCustomTreeView” instead to be able to decide which inherited “protected” members of a class should be declared as “published”. In my case I want the end user to have access to whole TTreeView component functionality at design-time, so I do not need to hide any inherited properties.

Additionally to the original viewer feature set I have also added the possibility to display children counts next to every non-empty JSON object or array, and estimated byte size of a given JSON tree node.

The main functionality of this component is implemented in its public “LoadJson” procedure that populates the tree view based on the content of connected “TJSONDocument” component.

In the next step I have used “TJSONDocument” and “TJSONTreeView” components to implement a simple JSON Viewer application. The functionality is minimal. You can clear the current contents of the JSON viewer using “Clear” button, or you can copy to clipboard a JSON text and paste it into the viewer window using “Paste” button. There is also a popup menu to control if children counts and node byte sizes are displayed or not. The application icon was created using IcoFX (http://icofx.ro/) directly from the JSON logo downloaded from the JSON home page.

Below is the screenshot from Delphi JSON Viewer at runtime. Just copy some JSON text to clipboard and paste…

Hide image

In a sense the “TJSONDocument” component can be considered the implementation of Document Object Model for JSON. But what about SAX for JSON? SAX – or Simple API for XML – presents a completely different approach to document parsing. Instead of building an in-memory representation of the document, it just goes through it and fires events for every syntactical element encountered. It is up to application to process the events it is interested in. For example to find something inside a large document.

Based on the “TJSONDocument” I have implemented an experimental “TJSONParser” component that implements SAX processing model for JSON. In reality the “SAX parser” for JSON should be implemented from scratch and directly parse JSON text and fire relevant events. In my case it sits on top of the in-memory representation of JSON.

The “jsonparser” unit contains the following enumerated type that lists different token types that can be found in a JSON text:

There is also a declaration of “TJSONTokenEvent” that is fired when a JSON token is encountered:

The “TJSONParser” class is derived from “TJSONDocument” and declared as follows:

The “TJSONParser” component can do two things. If you call “FireTokenEvents” public method, it will traverse the underlying JSON document and fire “OnToken” events for every token it encounters. It is also possible to build a token list in memory that can be accessed via “TokenList” property. This could be useful if we would like to implement JSON viewer using the Virtual Tree View component that requires fast access to the underlying data structure.

What was interesting during the implementation of these two methods was the fact the underlying documental traversal algorithm was the same for both firing the events and building the list. In order to avoid code duplication, I have decided to parameterize the traversal algorithm using anonymous methods.

The following anonymous method signature was defined in “jsonparser” unit:

The signature of this method matches “DoOnAddToTokenListEvent” and “DoOnFireTokenEvent” private methods in the declaration of the “TJSONParser” class.

The actual document traversal algorithm has been implemented inside “DoProcess” method that is called from both “FireTokenEvents” and “BuildTokenList” method in the following way:

In this way we have both functionalities implemented without code duplication inside the recursive “DoProcess” method:

The “TJSONParser” component can be used as a starting for arbitrary JSON processing at the lowest level of actual JSON text tokens. Delphi anonymous methods are really coolJ

JSON is currently probably the most important data interchange format in use. Its simplicity makes it easy to process and information encoded with JSON is typically smaller than using XML.

Over the years XML has become the whole family of specifications and it is not a trivial task to implement fully compliant XML parser from scratch.

Delphi 6 was the first commercial IDE on the market to introduce support for XML SOAP web services. Delphi 6 also introduced TXMLDocument component and XML Data Binding Wizard to make it easier to work with XML.

In the world of JSON slowly emerges the equivalent of XML Schema for JSON, which tries to create a meta representation of JSON. On the JSON home page you can find a reference to a draft version of IETF RFC “A JSON Media Type for Describing the Structure and Meaning of JSON Documents” [8]. This is still pending feedback but in future could be a starting point for implementing a “Data Binding Wizard for JSON”.

In this article I have described a JSON Viewer application implemented with Embarcadero Delphi XE. The source code that accompanies this paper is organized in the form of two packages for Delphi components – one runtime and one design-time – and the “djsonview”: Delphi VCL Forms application that implements the Delphi JSON Viewer.

The full source code described in this paper can be downloaded from [1].

1. Source code for this article (http://cc.embarcadero.com/item/27788)
2. Source code for this article as part of the RAD Studio XE demos on sourceforge (https://radstudiodemos.svn.sourceforge.net/svnroot/radstudiodemos/branches/RadStudio_XE/Delphi/DataSnap/JSONViewer)
3. JSON RFC (http://www.ietf.org/rfc/rfc4627.txt)
4. JSON: The Fat-Free Alternative to XML (http://www.json.org/fatfree.html)
5. JSON Home Page (http://www.json.org)
6. JSON Examples (http://www.json.org/example.html)
7. Apache Pivot JSON Viewer (http://pivot.apache.org/demos/json-viewer.html)
8. Simple API for XML Home Page (http://www.megginson.com/downloads/SAX/)
9. Draft JSON Schema (http://tools.ietf.org/html/draft-zyp-json-schema-02)
10. Embarcadero Delphi Home Page (http://www.embarcadero.com/products/delphi )

Paweł Głowacki is Embarcadero Technologies’ European Technical Lead for Delphi, RAD Studio and All-Access technologies. Previously, Paweł spent over 7 years working as a senior consultant and trainer for Delphi within Borland Education Services and CodeGear. As well as working with Embarcadero customers across the region, he also represents Embarcadero internationally as a conference and seminar speaker.

For more information check out Paweł’s technical blog at http://blogs.embarcadero.com/pawelglowacki

Hide image

Embarcadero Technologies, Inc. is a leading provider of award-winning tools for application developers and database professionals so they can design systems right, build them faster and run them better, regardless of their platform or programming language. Ninety of the Fortune 100 and an active community of more than three million users worldwide rely on Embarcadero products to increase productivity, reduce costs, simplify change management and compliance and accelerate innovation. The company’s flagship tools include: Embarcadero® Change Manager™, Embarcadero™ RAD Studio, DBArtisan®, Delphi®, ER/Studio®, JBuilder® and Rapid SQL®. Founded in 1993, Embarcadero is headquartered in San Francisco, with offices located around the world. Embarcadero is online at www.embarcadero.com.