Modeling a JSON message for use in a message map by using an equivalent XML schema model

If you do not have a JSON schema for your JSON message data, you can use the following procedure to create an equivalent XML schema model that can be used in one or more message maps.

About this task

Graphical data mapping requires a supported message model of your message data.

If you have a JSON schema for your message data, you can use it as described in Creating or transforming a JSON message by using a JSON schema. If you do not have a JSON schema, you can model a JSON message that contains JSON objects, JSON arrays, or both, by following the steps in this topic to create an equivalent XML schema model, which you can then use in one or more message maps with the Cast function in the Graphical Data Mapping editor. For more information, see Graphically modeling a JSON message in a message map.

The following steps detail how to use an XML schema model in one or more message maps to define the JSON data from a corresponding XML schema type. Alternatively, you can define the JSON data in-line in the map by using the Add User-Defined function.

Procedure

Complete the following steps to create a JSON message based on a schema model:

  1. Create a message map. Select one of the following JSON supplied models as the output of the map:
    • JSON (JSON object message model supplied by IBM) to create a JSON object message
    • JSON (JSON array message model supplied by IBM) to create a JSON array message

    For more information, see Creating a message map.

  2. Delete the predefined Data object. Choose one of the following options:
    • If you select JSON (JSON object message model supplied by IBM) in the previous step, delete the Data element of type JSONObject.

      Figure that shows context menu to delete the extra Data element in a JSON message.

    • If you select JSON (JSON array message model supplied by IBM) in the previous step, delete the Data element of type JSONArray_1.

      Figure that shows context menu to delete the extra Data element in a JSON message.

    Note: In the Graphical Data Mapping editor, you can only have one Data element in a JSON message if you use a schema model to define the JSON message.
  3. Qualify the Data element of type anyType by using the Cast function.

    For more information, see Casting elements in a message map.

    When you cast the JSON.Data.any on the input side of the map to define the JSON message, you can only use schema models that are defined in the default namespace.

    For example, if you build a JSON input with a cast to an element in a none empty namespace, the Mapping node runs without throwing an error. However, you might not get the expected output. You can use a user trace to see that the presence of the namespace can be deduced as the cause of the map failure:
    1. First, you see that the map successfully locates JSON.Data.
    2. Next, you see BIP message BIP3959I: The Mapping node is traversing the input tree by using the nodetest ''element(Data)'' and the relationship ''child''. The number of matching elements is ''1''.
    3. Finally, you see that the map fails to locate anything for the subsequent JSON objects. You see BIP message BIP3959I: The Mapping node is traversing the input tree by using the nodetest ''element({http://schema014_T}:testMsgNsImpIn)'' and the relationship ''child''. The number of matching elements is ''0''.

    When you cast the JSON.Data.any on the output side of the map to define the JSON message, you can use a schema element in a none default namespace. It is recommended that you use the default namespace.

    The Mapping node creates the elements with namespaces and the JSON serializer ignores them.

    Note: When you define a JSON message by using the Cast function, you must comply with the following rules:
    • You must define the schema definition for the type of a JSON object in the default namespace of the project where the map is defined.
    • You must define the schema definition for a JSON array in the target namespace: http://www.ibm.com/iib/msl/json.
    • You must use the following naming convention for the name of the type of a JSON array: JSONArray_unique_name, where unique_name is any combination of valid XML characters. For example, you can name a type as JSONArray_ofBooleans if the type is an array of Boolean elements. You can name a type JSONArray_ofMyAddrObjects if the type is a complex type.
    • The schema of a JSON array must contain a sequence with a single repeating element named Item.
    • Optionally, you can define the JSON object or JSON array as nillable in the schema model to support the JSON null value.
  4. Define transforms between the input elements and the output elements.
    • Use the Assign transform to set a fixed value without the use of input data.
    • Use the Create transform to create an empty element, or a nil element without the use of input data.
    • Use the Move transform to copy an input element value to the output element.
    • Use the If transform, a custom transform, or the XPath transform to define the condition that determines the value of an output element.
    • Use the Append transform, the Group transform, the For Each transform, the Join transform, a custom transform, or the XPath transform to set the value of a JSON array.
    • Use the Select transform or the Database Routine transform to set the value with data available in a database system.
    • Use the xs:type transform to cast the value of a simple input element to a specific data type.
    • Use the fn:type transform to set the value by using XPATH 2.0 functions.
    • Use the Custom Java transform to enter your own Java™ code.
    • Use the Custom ESQL transform to call your own ESQL code.

    For more information, see Specifying a transform (mapping operation).

Example

The following examples present XML schema types that model some example JSON data objects and arrays.

Example for a JSON object message

This example shows how to define a schema model for a JSON object message in the default namespace:
{ "Nam" : "A Name", "Num" : 1 }
The message tree for the JSON message is described in the following trace: 

(0x01000000:Object):JSON       = ( ['json' : 0x2f030fa0]
    (0x01000000:Object):Data = (
          (0x03000000:NameValue):Nam = 'A Name' (CHARACTER)
          (0x03000000:NameValue):Num = 1 (INTEGER)
    )
  )
The following code shows the schema file that defines the JSON object message: 

<?xml version="1.0" encoding="UTF-8"?>
   <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:complexType name="MyJsonObjType1">
    	<xsd:sequence>
    		<xsd:element name="Nam" type="xsd:string" nillable="true"></xsd:element>
    		<xsd:element name="Num" type="xsd:int" nillable="true"></xsd:element>
    	</xsd:sequence>
    </xsd:complexType>
</xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model MyJsonObjType1:

Figure that shows the JSON message that is defined in a map by using the cast function.

Example for a JSON array message

This example shows how to model a JSON message that is an array of Boolean elements. You define a schema model for the following JSON array message in the default namespace: 
[ true,false ]
The message tree for the JSON array message is described in the following trace: 
  
(0x01000000:Object):JSON       = ( ['json' : 0x292051a0]
    (0x01001000:Array):Data = (        
      (0x01000000:NameValue):Item  = TRUE (BOOLEAN)
      (0x01000000:NameValue):Item  = FALSE (BOOLEAN)      
     )
)
The following code shows the schema file that defines the JSON array message in the target namespace http://www.ibm.com/iib/msl/json: 

<?xml version="1.0" encoding="UTF-8"?>
  <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"  targetNamespace="http://www.ibm.com/iib/msl/json">
     <xsd:complexType block="#all" name="JSONArray_ofBoolean">
        <xsd:sequence>
            <xsd:element maxOccurs="unbounded" minOccurs="0" name="Item" nillable="true" type="xsd:boolean"/>
        </xsd:sequence>
   </xsd:complexType>
</xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model JSONArray_ofBoolean:

Figure that shows the JSON message that is defined in a map by using the cast function.

Example for JSON object message with an array of objects

This example shows how to model a JSON message that is an array of objects. 
[ { "nam":"one","val":1 },{ "nam":"two","val":2 }]
The message tree for the JSON object message is described in the following trace: 
  
(0x01000000:Object):JSON       = ( ['json' : 0x292051a0]
    (0x01001000:Array):Data = (      
                        (0x01000000:Object):Item = (
                                                  (0x03000000:NameValue):nam = 'one' (CHARACTER)          
                                                  (0x03000000:NameValue):val = 1  (INTEGER)      
                                                   )      
                        (0x01000000:Object):Item = (
                                                  (0x03000000:NameValue):nam = 'two' (CHARACTER)         
                                                  (0x03000000:NameValue):val = 2 (INTEGER)      
                                                  )
                             )
)

You define a schema model for the JSON object message in the default namespace.

The following code shows the schema file that defines the JSON array. You define the JSONArray_ofObjects type in the target namespace http://www.ibm.com/iib/msl/json: 

<?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/iib/msl/json">
         <xsd:complexType block="#all" name="JSONArray_ofObjects">
             <xsd:sequence>
                 <xsd:element maxOccurs="unbounded" minOccurs="0" name="Item" nillable="true">
                     <xsd:complexType>
                         <xsd:sequence>
                            <xsd:element name="nam" type="xsd:string" nillable="true"/>
                            <xsd:element name="num" type="xsd:int" nillable="true"/>
                         </xsd:sequence>
                    </xsd:complexType>
               </xsd:element>
            </xsd:sequence>
        </xsd:complexType>
 </xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model JSONArray_ofObjects:

Figure that shows the JSON message that is defined in a map by using the cast function.

Example for JSON Object message containing a JSON array

This example shows how to model a JSON object message that contains a JSON array. 
{ "state":"ok", "array":[ { "nam":"one","val":1 },{"nam":"two","val":2 } ] }
The message tree for the JSON object message is described in the following trace: 
  
(0x01000000:Object):JSON       = ( ['json' : 0x292051a0]
    (0x01000000:Object):Data = (      
             (0x03000000:NameValue):state= 'ok' (CHARACTER)
             (0x01001000:Array):array= (        
                             (0x01000000:Object):Item = (
                                                (0x03000000:NameValue):nam = 'one' (CHARACTER)          
                                                (0x03000000:NameValue):val = 1  (INTEGER)        
                                                         )        
                             (0x01000000:Object):Item = (
                                                (0x03000000:NameValue):nam = 'two' (CHARACTER)          
                                                (0x03000000:NameValue):val = 2 (INTEGER)        
                                                         )
                                         ) 
                              )
)
The object message is defined in the default namespace and imports the type of the JSON array element from the second schema. The following code shows the schema file that defines the JSON object message:

<?xml version="1.0" encoding="UTF-8"?>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:mjatns="http://www.ibm.com/iib/msl/json">
      <xsd:import namespace="http://www.ibm.com/iib/msl/json" schemaLocation="MyJsonArrayTypes.xsd"/>
         <xsd:complexType name="MyJsonObjWithArrayType1">
             <xsd:sequence>
                 <xsd:element name="state" type="xsd:string" nillable="true"></xsd:element>
                 <xsd:element name="array" type="mjatns:JSONArray_ofObjects" nillable="true"></xsd:element>
              </xsd:sequence>
         </xsd:complexType>
    </xsd:schema>
The following code shows the schema file that defines the JSON array. You define the JSONArray_ofObjects type in the target namespace http://www.ibm.com/iib/msl/json: 

<?xml version="1.0" encoding="UTF-8"?>
   <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.ibm.com/iib/msl/json">
       <xsd:complexType block="#all" name="JSONArray_ofObjects">
           <xsd:sequence>
                <xsd:element maxOccurs="unbounded" minOccurs="0" name="Item" nillable="true">
                                  <xsd:complexType>
                                             <xsd:sequence>
                                                   <xsd:element name="nam" type="xsd:string" nillable="true"/>
                                                   <xsd:element name="num" type="xsd:int" nillable="true"/>
                                             </xsd:sequence>
                                  </xsd:complexType>
                </xsd:element>
         </xsd:sequence>
     </xsd:complexType>
    </xsd:schema>

The following figure shows the map after you cast the Data element of the JSON object message to the schema model MyJsonObjWithArrayType1:

Figure that shows the JSON message that is defined in a map by using the cast function.

Note: The XML schema can be extended if you need to use the message model in another IBM Integration Bus component, for example a Route node or a monitoring event from a message flow node. For the map cast, you can define an XML schema type, for example MyJsonObjType1. If you want to use the schema type in the XPath expression builder, for setting a match expression for the Route node or the monitoring event data path, you add a schema element definition for the "Data" element of the JSON domain as follows:
<xsd:element name="Data" type="MyJsonObjType1"></xsd:element>

What to do next

Deploy the message map and verify that the output message is valid. For more information, see Troubleshooting a message map.