Constructing Working Data XML to Map to JSON

JSON has Objects {} that contain an unordered list of key:value pairs and Arrays [ ] that contain an ordered list of values. Values are implicitly typed as either string, number, boolean, or null. The values in a JSON array need not be of the same type. Key names have no special restricted characters; this means they have the same allowed character set as string values. Some special characters in strings must be escaped with an escape character sequence using the backslash character \.

There are several considerations when constructing Working data variables to map to or from JSON data:

General Rules

Note the following general rules:

Type

XML value types are defined separately from the XML data itself, typically in an XSD schema. RESTCaller does not have access to the .XSD schema for the bodyXML, and instead relies on a default mapping scheme with element name type hint prefixes to distinguish non-default types. If the type hints are not used, by default an Element with child Elements is interpreted as a JSON Key with an Object value, and an Element with no child Elements is interpreted as a JSON key with a string value. For example:

<myObject>
       <myString>string value</myString>
       <myNumber>123456</myNumber>
       <myBooelan>true</ myBooelan >
<myObject>

Will be:

"myObject": {
               "myString": "string value",
               "myNumber": "123456",
               "myBoolean": "true"
       }

Note that the values for myNumber and myBoolean are quoted and therefore typed as strings in the JSON structure which is incorrect. The type hint prefixes override this default behavior allowing JSON Array, Number and Boolean values to be set correctly. The type hint prefixes are:

To use a type hint prefix, prepend the appropriate type hint prefix to the name of the element. For example, if an element named myNumber is typed as some form of number (integer, long, float, double) such as 123456, then prefixing its name with _vn will create an element as follows:

<_vomyObject>
       <_vsmyString>string value</_vsmyString>
       <_vnmyNumber>123456</_vnmyNumber>
       <_vnmyBoolean>123456</_vnmyBoolean>
<_vomyObject>

When this element is sent as JSON, the RESTCaller service will remove the type hint prefix when converting the element name to a JSON key name. Using this example, the JSON key:value will be:

"myObject": {
               "myString": "string value",
               "myNumber": 123456,
               "myBoolean": true
       }
Important: Because the type hint prefix is removed before the name is converted to a JSON key name, the type hint prefix should not be considered as part of the name for the purposes of uniqueness. Note that the Working Data editor in SBM Composer is unaware of the RESTCaller type hint prefixes and cannot enforce uniqueness if the type hint hides the duplicate name.

For receiving JSON data, by default the JSON key names will become the XML element names and values will convert to the element text value in the case of strings, numbers, and booleans. For object and array values, a containing element named for the key will be created. Object properties will be sub-elements in any order. Array item values will be held in multiple repeating <Item> elements in the specified array order. Object and Array conversion is discussed in more detail in the structures below.

Tip: Use the returnJSONTypeHints option to receive data with elements prefixed with the JSON type hints _vo, _va, _vs, _vn, vb as appropriate.

Structure – Objects

Elements with PrivateComplexType map to JSON objects by default. For example, this XML structure:

<JsonDoc>
       < myObject>…</myObject>
</JsonDoc>

maps to the JSON document:

{
"myObject": { …
       }
}

Elements that are children of the PrivateComplexType Element map to the key:values of a JSON object by default. This XML structure:

<JsonDoc>
       < myObject>
               <aMember>a member value</aMember>
               <bMember>b member value</bMember>
               <cMember>c member value</cMember>
       </myObject>
</JsonDoc>

maps to the JSON document:

{
"myObject": { 
               "cMember": "c member value",
               "bMember": "b member value",
               "aMember": "a member value"
               }
}
Note: The object members may appear in a different order within the Object value because JSON object members are unordered. Each member should have a unique key name within the object.

The type hint name prefix, _vo, may be optionally be used. Typing hint name prefixes are removed to create the JSON name. Since the type hint gets removed from the element name when converting to JSON, it should not be considered as part of the key name for the purposes of uniqueness. This XML structure:

<JsonDoc>
       < _vomyObject>
               <aMember>a member value</aMember>
               <bMember>b member value</bMember>
               <cMember>c member value</cMember>
       </_vomyObject>
</JsonDoc>

maps to the JSON document:

{ 
"myObject": { 
               "aMember": "a member value",
               "bMember": "b member value",
               "cMember": "c member value"
       }
}

Structure – Arrays

Elements that are children of the Private ComplexType can be used to declare arrays but special a type hint name prefix, _va, must be used to distinguish it from an object and ensure the correct JSON structure is created.

If the JSON array contains values of the same type, a repeating element can be used to define the array values. The special name—Item—should be used to name this element in order to be consistent with data that is converted from JSON. The child Item element can have a type hint prefix to indicate its type. For example, refer to the following XML structure:

<JsonDoc>
       <_vamyArray>
               <_vnItem>123</_vnItem>
               <_vnItem>456</_vnItem>
       </_vamyArray >
</JsonDoc>

Maps to the JSON document
{ "myArray": [ 
               123,
               456
               ]
}
Important: Due to the way the XML to JSON conversion works, it detects repeating elements in the XML and attempts to convert them to JSON arrays. However, this works inconsistently and it is strongly recommended to use the pattern described here with an array type hint prefix on a containing element that names the array key with a contained repeating element to hold the array values.
Important: JSON arrays can contain mixed value types. That is, a JSON array can contain string, number, array, object or Boolean mixed together. This case is not currently supported.

Sending Empty Arrays, Objects, and Strings

To send empty arrays, objects, and strings you must use the appropriate prefix (listed below), otherwise the default is a string.

JasonDoc defaults to a string value "", and if it is empty then "" is sent.

The same rules apply to object named values and array Item values.

Value defaults to an string value "", and if it is empty then "" is sent.

Item defaults to an string value "", and if it is empty then "" is sent.

Character Escaping

XML element names use a restricted set of UNICODE characters with some special rules. JSON key names can use any UNICODE character with the exception that a small set of control characters must be escaped rather than used directly. Because of these differences, JSON key names cannot necessarily be directly used as XML element names and it is not possible to model any JSON key name using an XML element name.

To overcome this, RESTCaller provides a character escaping mechanism for XML element names that allows XML element names to model almost any JSON key name. Character escaping works by substituting the desired character that cannot be used with a special "escape" character followed by a code character that indicates the desired character. RESTCaller uses the underscore, '_' , as the special "escape" character and defines the following codes:

Name XML Escape JSON Character
Start _ The char that follows the _
SPACE _w ' '
UNDERSCORE __ '_'
HEXCHAR _xhhhh The Unicode char with the hex value hhhh
BACKSPACE _b \b
FORDFEED _f \f
LINEFEED _n \n
RETURN _r \r
TAB _t \t
QUOTE _q \q
FORWARDSLASH _s \/
BACKSLASH _c \\
UTF16HEX _uhhhh \uhhhh

XML Start Characters

XML allows less characters to be used for the first character of the element name than it does for following characters. If the JSON key name starts with one of these illegal start characters, it can be modeled in XML with the _ escape and will be escaped by the REST caller when the JSON is mapped to XML. For example, XML element names cannot start with a number (0 through 9). If the desired JSON has a key name "10x10", this can be declared in XML as <_10x10>. This "start" escape can only be used on the first character of the XML name. Only invalid start characters that are otherwise valid name characters can be escaped this way and only if they are the first character of the element name.

Note: Type hint prefixes do not count as part of the element name. If type hint prefixes are used, the start character is the character immediately following the type hint prefix. For example, the start character of the element name _vs1000 is 1, which is an invalid start character and must be escaped as _vs_1000.
Note: Namespace name qualifiers are ignored for this purpose, which is why XML structures that map to JSON data must be declared with no namespace.

UNDERSCORE

Because RESTCaller uses the _ character as an escape, it must be escaped so that the JSON key can contain an _ character. _ was chosen because it is a valid XML start character.

HEXCHAR

Illegal XML characters can be encoded with the HEXCHAR escape sequence, where the illegal character is expressed as a sequence of 4 hex digits that correspond to the UNICODE character hexadecimal code point value. For example, the char +, is _h002B. The purpose of this is to allow the character to pass un-escaped in the JSON data. It should only be used for characters that cannot be directly represented in an XML name, but can appear directly in a JSON string.

BACKSPACE, FORMFEED, LINEFEED, RETURN, TAB, QUOTE, FORWARDSLASH, BACKSLASH, UTF16HEX

These escapes correspond to the JSON escapes for various special control characters. Control characters (U+0000 through U+001F) without a special escape must be represented using with \uhhhh where hhhh is the UNICODE character hexadecimal code point value. For example, the char Vertical Tab, is _u000A.

Note: JSON allows any character to be represented this way but it is unclear if such a representation is un-escaped by the consumer or by the JSON parser, so the behavior of this escape may vary.
Note: Unicode surrogate pairs are not currently supported.