• Introduction

PilotFish specializes in transforming a whole range of Formats to and from XML. One important Format when dealing with APIs is JavaScript Object Notation, or JSON. The structures of JSON and XML are similar, however JSON has several constructs such as arrays that have no counterpart in XML.

In order to work more precisely with JSON, PilotFish now provides a special JSON-XML schema. This schema provides special elements and attributes to describe unique JSON features in the XML, allowing for a JSON message to be constructed with far more precision than the more general conversion in past PilotFish versions.

This document will cover how to use the JSON-XML schema to build JSON messages.

• Transformer Versions – 1.0 vs 2.0

JSON-XML was added to the JSON Transformation Module in the PilotFish application for the 18R1 release of the eiPlatform/eiConsole. Because this style of converting JSON to/from XML was so different from past approaches, the JSON Transformer was versioned for this release.

Version 1.0 is the old, non-JSON-XML style of converting JSON to/from XML. Any existing JSON transformations from eiPlatform/eiConsole installations versions 17R2 or older will still default to using this option. It will convert JSON to XML and XML to JSON, however without using the JSON-XML schema the conversion will be less precise and special JSON constructs like arrays will be hard to define.

Version 2.0 is the new, JSON-XML style of conversion. JSON messages get converted into XML using the JSON-XML schema, and JSON-XML documents are converted into precisely constructed JSON messages.

If there are existing transformations in production using Version 1.0, it is recommended that they are left alone unless there is a need for more precise handling of the JSON in XML. For all future transformations, it is highly recommended to stay with the new JSON-XML in Version 2.0.

• JSON Format Builder

To make building JSON-XML in the PilotFish eiConsole as easy as possible, a JSON Format Builder has been provided in the Data Mapper. Simply pass in any existing JSON file, and it will convert it to JSON-XML and create a format for it. This allows for building JSON-XML through the drag-and-drop capabilities of the PIlotFish Data Mapper.

Please be aware that the JSON Format Builder supports both the 1.0 and 2.0 versions of the JSON Transformer, and will produce the XML format based on the version that is selected. For working with JSON-XML, always choose Version 2.0

• Quick Overview

This is a quick overview of what a JSON-XML document looks like, and the basic features of how it works.

This is a JSON-XML document:

And this is the JSON it is transformed into:

The following sections will explain each part of the JSON-XML schema and how it contributes to generating the output JSON.

• Namespace

JSON-XML documents rely on elements within a special namespace to properly define their structure. This namespace must be declared on the root element of the document to indicate to the JSON Transformer that it is handling JSON-XML. Only a handful of elements are used with this namespace in the document because they are assigned very specific behavior.

The JSON-XML namespace declaration and root element is always the same:

<json:JSON xmlns:json=”http://www.pilotfishtechnology.com/schemas/json” />

• Namespace Elements

The JSON-XML namespace is used for only a handful of elements within the document. These elements represent unnamed structures within the JSON. There are two scenarios where a structure within the JSON wouldn’t be tied to a named property. The first is the root object/array, which by default is never named. The second is elements within an array, which are ultimately referenced by index and not a name.

These elements are never used to define anything that is tied to a JSON property name.

There are only three JSON-XML namespaced elements:

<json:OBJECT /> – This represents an unnamed JSON Object. This element is only used as the top-level element of the JSON structure, or as an object that is an element within an array.

<json:ARRAY /> – This represents an unnamed JSON Array. This element is only used as the top-level element of the JSON structure, or as an array that is an element within another array.

<json:ELEMENT /> – This represents an unnamed JSON value that is an element within an array. This cannot have a value that is another Object or Array, it must be a simple value type. The “pf_json_type” attribute can be assigned to this element to more clearly define the type of value it contains.

• Non-Namespace Elements

In JSON-XML, elements outside of the JSON-XML namespace are treated as properties within a JSON object. The name of the element becomes the property name, and its text content becomes the value.

For example:

<PropertyName>Value</PropertyName>

All non-namespace elements can be assigned the “pf_json_type” attribute to more clearly define the type of value it contains.

• Defining JSON Types

XML does not natively support a wide range of value types. Elements with child elements are like objects, and the text content of elements are treated as strings. JSON has a much wider range of value types, and therefore JSON-XML provides the means to support those types through the “pf_json_type” attribute. This attribute can be assigned to any non-namespace element or to the <json:ELEMENT /> element to more clearly define the type of that element’s value.

By default, any XML element with a simple value is treated as a string. Also by default, any XML element with child elements is treated as a JSON object. So this XML without the “pf_json_type” attribute:

Is equivalent to this XML with the attribute:

And both will transform into this JSON:

More commonly, the “pf_json_type” attribute is used to change the default behavior of the value of the elements it is assigned to. The following are the available values for this attribute, and the effect they have:

array – Treats the child elements of the element it is assigned to as elements in a JSON array. All child elements should be JSON-XML namespace elements, because array elements have no property names.

boolean – Treats the text content of this element as a boolean. Value can only be “true” or “false”.

float – Treats the text content of this element as a floating point, or decimal, number. Value must be numeric.

int – Treats the text content of this element as an integer, or whole, number. Value must be numeric and non-decimal.

null – Treats the text content of this element as a null value. Value must be blank (ie, empty element ).

object – Treats the child elements of the element it is assigned to as properties in a JSON object. This is the default for child element handling if no “pf_json_type” is assigned.

string – Treats the text content of this element as a string. This is the default for text content handling if no “pf_json_type” is assigned.