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 uses a specific XML format that is predetermined by a corresponding XML schema.

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

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.

In order 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 module guide 923 0 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

In order to convert a message in JSON format into XML format, the JSON adaper 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 (key : value). 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>

Example: XML to JSON Conversion

Input message in JSON format

The example demonstrates the JSON structure:

{
  "widget": {
      "debug": "on",
      "window": {
        "title": "Sample Confabulator Widget",
        "name": "main_window",
        "width": 500,
        "height": 500
      },
      "image": {
        "src": "Images/Sun.png",
        "name": "sun1",
        "hOffset": 250,
        "vOffset": 250,
        "alignment": "center"
      },
      "text": {
        "data": "Click Here",
        "size": 36,
        "style": "bold",
        "name": "text1",
        "hOffset": 250,
        "vOffset": 100,
        "alignment": "center"
      }
  }
}

Output message in XML format

The following out demonstrates the result of a JSON to XML conversion:

<?xml version="1.0" encoding="UTF-8" ?>
<object>
  <object name="widget">
    <string name="debug">on</string>
    <object name="window">
      <string name="title">Sample Confabulator Widget</string>
      <string name="name">main_window</string>
      <number name="width">500</number>
      <number name="height">500</number>
    </object>
  <object name="image">
      <string name="src">Images/Sun.png</string>
      <string name="name">sun1</string>
      <number name="hOffset">250</number>
      <number name="vOffset">250</number>
      <string name="alignment">center</string>
    </object>
    <object name="text">
      <string name="data">Click Here</string>
      <number name="size">36</number>
      <string name="style">bold</string>
      <string name="name">text1</string>
      <number name="hOffset">250</number>
      <number name="vOffset">100</number>
      <string name="alignment">center</string>
    </object>
  </object>
</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

  • Conversion Mode

    • 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 to use 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.

  • Name of root element (available only for JSON to XML conversion mode and for Domain-specific XML)

    To specify the root element, e.g.: root

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