SBM Orchestration Guide → Calling RESTful Web Services from an Orchestration Workflow → 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 \.
Note the following general rules:
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 }
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.
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" } }
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" } }
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 ] }
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.
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 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.
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.
Copyright © 2007–2015 Serena Software, Inc. All rights reserved.