JSON Adapter

Usage

The JSON Adapter converts messages containing structured data in JavaScript Object Notation (JSON) into XML format and, vice versa, messages from XML into JSON format.

For the conversion, the adapter supports different XML formats:

  • Generic XML

    • Abstracts from the JSON structure, so that JSON keys and values are mapped via attribute and element values

  • Domain specific XML

    • Adapts the JSON structure, so that JSON keys become element names and JSON values become element values

  • XSLT 3.0 specific XML

    • Abstracts from the JSON structure (similar to Generic XML) into an XSLT-specific format

Comparison:

  • JSON

  • Generic XML

  • Domain XML

  • XSLT 3.0

{
  "distance": {
    "desc": "Distances between several cities, in kilometers.",
    "updated": "2014-02-04T18:50:45",
    "uptodate": true,
    "author": null,
    "cities": {
      "Brussels": [
        {
          "to": "London",
          "distance": 322
        },
        {
          "to": "Paris",
          "distance": 265
        }
      ]
    }
  }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<object>
    <object name="distance">
        <string name="desc">Distances between several cities, in kilometers.</string>
        <string name="updated">2014-02-04T18:50:45</string>
        <boolean name="uptodate">true</boolean>
        <null name="author"/>
        <object name="cities">
            <array name="Brussels">
                <object>
                    <string name="to">London</string>
                    <number name="distance">322</number>
                </object>
                <object>
                    <string name="to">Paris</string>
                    <number name="distance">265</number>
                </object>
            </array>
        </object>
    </object>
</object>
<?xml version="1.0" encoding="UTF-8"?>
<distance>
    <uptodate>true</uptodate>
    <cities>
        <Brussels>
            <distance>322</distance>
            <to>London</to>
        </Brussels>
        <Brussels>
            <distance>265</distance>
            <to>Paris</to>
        </Brussels>
    </cities>
    <author>null</author>
    <updated>2014-02-04T18:50:45</updated>
    <desc>Distances between several cities, in kilometers.</desc>
</distance>
<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.w3.org/2005/xpath-functions">
    <map key="distance">
        <string key="desc">Distances between several cities, in kilometers.</string>
        <string key="updated">2014-02-04T18:50:45</string>
        <boolean key="uptodate">true</boolean>
        <null key="author"/>
        <map key="cities">
            <array key="Brussels">
                <map>
                    <string key="to">London</string>
                    <number key="distance">322</number>
                </map>
                <map>
                    <string key="to">Paris</string>
                    <number key="distance">265</number>
                </map>
            </array>
        </map>
    </map>
</map>

To configure the JSON Adapter, refer to Dialog JSON Adapter - Settings.

Generic XML

For the XML-JSON conversion mode, you must provide the XML input message in the required XML format. For schema verification, the correct json.xsd schema is made available in the repository.

Creating Input Message for the XML-JSON Adapter

For the XML > JSON processing mode, the JSON Adapter expects an input message with a specific XML format that can be validated by using the provided XML schema.

To convert your input message in the required format, you use the XML schema provided in the Repository and together with an XSLT Converter module.

You can find the XML schema in the Repository at Global > System > Schemas > Json > json.xsd.

Proceed as follows

  1. Create an XSLT Converter to generate an input message.

  2. Connect the XSLT Converter with your JSON Adapter.

  3. Open the XSLT Converter for editing.

  4. In the XML source file area, open the burger menu menu and select Open > Repository. The Repository Explorer is displayed.

  5. Open the directory Global > System > Schemas > Json and select the `json.xsd `schema file.

  6. Click the OK button. The Explorer closes and the schema file is displayed.

  7. Based on this schema file, create the input message in the required format:

    Refer to

The XSLT Converter creates the specific XML format expected by the JSON Adapter.

Conversion Rules for JSON > XML

To convert a message in JSON format into XML format, the JSON adapter applies the conversion rules listed below.

Since all valid JSON documents start either with an object or an array, the root element in the XML format also consists either of an <object> or an <array> element.

Object

A JSON object becomes an <object> element.

The object itself may in turn contain a subordinate list of comma-separated properties. These properties are specified in the form of a key : value-pair. The key is always a string and is mapped to a name attribute in the XML result. The value can be an object, an array, a Boolean value, a string, number or null.

JSON XML 
{
  "Company" : "Virtimo"
}
 
<object>
    <string name="Company">Virtimo</string>
</object>

Array

A JSON array becomes an <array> element.

It contains a comma-separated list of values of the same or of different types. In the case of a JSON object property, the XML result contains a name attribute that corresponds to the property key.

JSON XML 
{
  "phoneNumbers": [
    "323 123-1111",
    "423 345-2222"
  ]
}
 
<array name="phoneNumbers">
    <string>323 123-1111</string>
    <string>423 345-2222</string>
</array>

Boolean

A JSON boolean becomes a <boolean> element.

If the value of a JSON object property is concerned, the XML result contains a name attribute that corresponds to the property key. The <boolean> value is either true or false.

JSON XML 
{
  "remote": false
}
 
<boolean name="remote">false</boolean>

String

A JSON string becomes a <string> element.

If the value of a JSON object property is concerned, the XML result contains a name attribute that corresponds to the property key. The string value is character data.

JSON XML 
{
  "name" : "Hello World"
}
 
<string name="name">Hello World</string>

Number

A JSON number becomes a <number> element.

If the value of a JSON object property is concerned, the XML result contains a name attribute that corresponds to the property key. The number value is a number.

JSON XML 
{
  "width" : 15.5
}
 
<number name="width">15.5</number>

Null

A JSON value of null becomes a <null> element.

If the value of a JSON object property is concerned, the XML result contains a name attribute that corresponds to the property key.

JSON XML 
{
  "furtherDetails" : null
}
 
<object>
    <null name="furtherDetails" />
</object>

Dialog JSON Adapter - Settings

This dialog offers the following options:

Base settings

  • Processing mode

    • JSON to XML

      Converts input messages in the JSON format into an XML format that is valid according to the respective XML schema.

    • XML to JSON

      Converts data from the predefined XML format into a JSON format. You can create the XML input message by using an XSLT Converter module, refer to Creating Input Message for the XML-JSON Adapter.

      The adapter always produces a JSON output format encoded in UTF-8.

Type of XML conversion

  • Generic XML

    To use Generic XML, select the option Generic XML.

  • Domain-specific XML

    To use domain-specific XML, select the option Domain-specific XML.

    When using the domain-specific XML to convert an input message, we strongly recommend using the domain-specific XML for converting the same message as an output message.

  • XSLT 3.0 conform XML

    To use XSLT 3.0 conform XML, select the option XSLT 3.0 conform XML.

    For the JSON to XML processing mode, the following limitations apply:

    • JSON texts must be enclosed with { }.

    • JSON text must not start with an array [ ].

    • JSON tags are not validated whether they are XML compliant.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen